Merge branch 'main' into feat/utils-identity

Author: jlukic

ai/research/data-sync/plan.md

@@ -199,6 +199,14 @@ Notes:
 - `pruneChildPaths` yields the changed path set — value-less and index-addressed (the reactivity review's finding), so the wire write picks values via `get` per path, and array segments translate to id-addressed form for schema-declared keyed arrays before send (see Repeating groups)
 - Clone cost is a non-goal: Meteor-era apps cloned liberally and stayed fast where it mattered. The place it would compound — per-inbound-delta apply — is avoided by field swaps incidentally, not as a crusade
 
+### Write capture — `trackWrites`
+
+`trackWrites(doc, fn, opts)` is the layer's write-capture primitive, lifted from its first consumer (`Signal.mutate`). It runs the mutator body and reports `{ changed, result, paths }` — `paths` only when `returnPaths: true`. The data layer always passes `returnPaths: true`, and `onWrite` for the per-write streaming path (outbox append, optimistic dep fires); a signal passes `returnPaths: false` because a signal's reactive granularity is the whole cell, so a path has nowhere to route — `returnPaths: false` is the floor, the data layer lives above it. The body runs synchronously: the tracked proxy expires at callback return, which is the root of the sync-only mutator constraint, not a separate rule.
+
+The contract the layer relies on is that `paths` is deliberately thin — value-less, kind-less, positional (see the Write Path note above on `pruneChildPaths`, and Repeating groups for id-addressing). Richness is reconstructed by the consumer at the point it is needed, not carried in the capture: new values read via `get(doc, path)` against the post-apply doc, op-kind inferred from value-presence (undefined means cleared) plus channel-membership re-match, base values taken from the rebase shadow — never the proxy trap, whose intermediate value is a partially-rebased replay artifact — and id-addressed array paths translated by schema-aware lookup at commit. The capture stays a position log because every richer datum has a more authoritative downstream source; widening the return would only manufacture a second, staler one.
+
+`trackWrites` is the owned-write engine — a mutation the layer performs and watches, both the client optimistic apply and the server authoritative apply. Its twin is `detectChanges(before, after)`, which diffs two finished images rather than watching a mutation, and is the external-write engine behind `watch()` CDC (External Writers). Owned writes capture, external writes diff — the dual-stream router's two capture engines, not redundant paths.
+
 ## Execution Without Fibers
 
 Meteor's server-side sync CRUD was fibers suspending the stack during I/O. Node removed that, Meteor 3 paid with `insertAsync` everywhere. This design splits the problem by what actually blocks:

ai/skills/authoring/component-composition.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `component-composition`
 > **Purpose:** How to structure parent-child component relationships — when to use configuration, slots, passed templates, or imperative coordination.
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -59,7 +59,7 @@ The core is a single `{#each}...{else}...{/each}` block:
 <div class="{uiClasses}menu" part="menu">
   {#each item in items}
     <menu-item
-      active={isValueActive value item}
+      active={isCurrentValue value item}
       href={item.href}
       value={item.value}
       exportparts="item"

ai/skills/authoring/component-css.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `component-css`
 > **Purpose:** Canonical patterns for writing CSS inside a component's shadow DOM — nesting, container queries, responsive design, state management, theming, and design token usage.
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -46,16 +46,16 @@ Write minimal, maintainable CSS that leverages the design token system and mirro
 
         .header {
           font-weight: var(--bold);
-          margin-bottom: var(--compact-spacing);
+          margin-bottom: var(--spacing-xs);
         }
 
         .items {
           display: flex;
           flex-direction: column;
-          gap: var(--compact-spacing);
+          gap: var(--gap-xs);
 
           .item {
-            padding: var(--compact-spacing);
+            padding: var(--padding-xs);
             cursor: pointer;
 
             &:hover {
@@ -84,7 +84,7 @@ Write minimal, maintainable CSS that leverages the design token system and mirro
 
       .actions {
         display: flex;
-        gap: var(--compact-spacing);
+        gap: var(--gap-xs);
       }
     }
   }
@@ -371,7 +371,7 @@ Semantic UI uses a sophisticated theme system where CSS variables automatically
 /* Allow external override */
 my-component {
   --component-max-width: 800px;
-  --component-spacing: var(--compact-spacing);
+  --component-spacing: var(--spacing-xs);
 }
 ```
 

ai/skills/authoring/component-patterns.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `component-patterns`
 > **Purpose:** Decision trees and production patterns for component communication, DOM querying, race condition prevention, resource cleanup, async reactions, lazy loading, scroll handling, and key anti-patterns.
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -46,30 +46,22 @@ How should component A talk to component B?
 Use when a child needs to read or mutate parent state. The child knows about the parent by name.
 
 ```javascript
-// todo-item.js — child component
-const createComponent = ({ self, data, findParent }) => ({
-  getTodos() {
-    return findParent('todoList').todos;
+// panel.js — child accesses parent coordinator, then drives its state
+const createComponent = ({ el, self, findParent, settings }) => ({
+  getPanels() {
+    return findParent('uiPanels');
   },
-  toggleCompleted() {
-    const todos = self.getTodos();
-    todos.toggleItemProperty(data.task._id, 'completed');
+  minimize() {
+    const panels = self.getPanels();
+    settings.minimized = true;
+    panels.setPanelMinimized(panels.getPanelIndex(el));
   },
 });
 ```
-*Source: `docs/src/examples/framework/todo-list/todo-item.js`*
+*Source: `src/components/panels/panel.js`*
 
 The argument to `findParent` is the **camelCase component name**, not the tag name. `findParent('uiPanels')` finds `<ui-panels>`, not `findParent('ui-panels')`.
 
-```javascript
-// panel.js — child accesses parent coordinator
-getPanels() {
-  const panels = findParent('uiPanels');
-  return panels;
-},
-```
-*Source: `src/components/panels/panel.js`*
-
 ### Pattern 2: Parent listens to child via event delegation
 
 Use when the parent needs to react to child lifecycle or user actions without the child needing a reference to the parent.
@@ -120,7 +112,7 @@ $('context-menu.box').settings({
   ],
 });
 ```
-*Source: `docs/src/examples/context-menu/page.js`*
+*Source: `docs/src/examples/component/context-menu/page.js`*
 
 Use `initialize` instead of `settings` when the script may run before the component is in the DOM.
 

ai/skills/authoring/component-specs.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `component-specs`
 > **Purpose:** Guide to the @semantic-ui/specs package — declarative component metadata, spec file format, SpecReader API, shared terms system, and build pipeline integration for spec-driven web components.
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -76,7 +76,7 @@ Property Definitions & Attribute Mapping
 **Parallel Pipeline for Documentation**:
 ```
 Component Definition (button.spec.js)
-    ↓ SpecReader.getDefinition()
+    ↓ DocsSpecReader.getDefinition()
 Documentation Objects with Examples
     ↓ Template System
 Rendered Documentation Pages
@@ -198,7 +198,7 @@ Tiers are cumulative: `standard` ⊂ `extended` ⊂ `full`. The value is the **l
 At build time, these are aggregated into `dist/presets.json` which the CDN upload script reads and publishes to R2. The CDN Worker uses presets to resolve URLs like `/core@canary/standard` into the correct set of component imports.
 
 Tiers:
-- **`standard`** (~40-50 components) — General-purpose UI for building typical apps. The "don't think about it" default.
+- **`standard`** — General-purpose UI for building typical apps. The "don't think about it" default.
 - **`extended`** — Standard + specialized components (rich form inputs, data viz, niche patterns).
 - **`full`** — Every user-facing component.
 
@@ -526,8 +526,12 @@ const componentSpec = reader.getWebComponentSpec();
 ### Generating Documentation
 
 ```javascript
+// Doc-generation methods live on DocsSpecReader (also from '@semantic-ui/specs')
+import { DocsSpecReader } from '@semantic-ui/specs';
+const docsReader = new DocsSpecReader(buttonSpec);
+
 // Get complete definition with examples
-const definition = reader.getDefinition();
+const definition = docsReader.getDefinition();
 
 // Result structure:
 {
@@ -539,28 +543,28 @@ const definition = reader.getDefinition();
 }
 
 // Generate navigation menu for documentation
-const menu = reader.getDefinitionMenu();
+const menu = docsReader.getDefinitionMenu();
 
 // Get ordered examples for display
-const examples = reader.getOrderedExamples();
+const examples = docsReader.getOrderedExamples();
 ```
 
 ### Attribute Dialect Support
 
-SpecReader supports three attribute dialects for flexibility:
+`getCodeFromModifiers` lives on `DocsSpecReader` and renders example code in three attribute dialects:
 
 ```javascript
 // Standard dialect (modifier-based)
-reader.getCodeFromModifiers('large primary');
+docsReader.getCodeFromModifiers('large primary');
 // Result: <ui-button large primary>Click Me</ui-button>
 
 // Verbose dialect (explicit attributes)
-const verboseReader = new SpecReader(spec, { dialect: 'verbose' });
+const verboseReader = new DocsSpecReader(spec, { dialect: 'verbose' });
 verboseReader.getCodeFromModifiers('large primary');
 // Result: <ui-button size="large" emphasis="primary">Click Me</ui-button>
 
 // Classic dialect (class-based)
-const classicReader = new SpecReader(spec, { dialect: 'classic' });
+const classicReader = new DocsSpecReader(spec, { dialect: 'classic' });
 classicReader.getCodeFromModifiers('large primary');
 // Result: <ui-button class="large primary">Click Me</ui-button>
 ```

ai/skills/authoring/component-theming.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `component-theming`
 > **Purpose:** Build custom components whose styles automatically adapt to light/dark mode and respond to runtime theme changes
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -109,7 +109,7 @@ Some visual effects genuinely need different parameters per theme (e.g., shadows
 
   @container style(--dark-mode: true) {
     backdrop-filter: blur(8px) brightness(1.1);
-    box-shadow: 0 0 20px var(--primary-color-20);
+    box-shadow: 0 0 20px var(--primary-20);
   }
 
   @container style(--light-mode: true) {

ai/skills/authoring/example-curriculum.md

@@ -24,7 +24,7 @@ The first 7 carry the core argument. The rest fill pattern gaps. Each entry list
 
 ### 1. `minimal` — The Floor
 
-A complete component in 6 lines. Inline template and CSS as strings. This is the absolute minimum — proof that the simplest case is trivially simple before any complexity is introduced.
+A complete component in a few lines. Inline template and CSS as strings. This is the absolute minimum — proof that the simplest case is trivially simple before any complexity is introduced.
 
 **New patterns:** Inline template/CSS strings (no `getText`), `onCreated` lifecycle hook, `formatDate` helper.
 

ai/skills/authoring/reactive-state.md

@@ -11,7 +11,7 @@ type: skill
 
 > **Skill:** `reactive-state`
 > **Purpose:** Comprehensive guide to the @semantic-ui/reactivity package — a standalone signals-based reactive system with automatic dependency tracking for state management.
-> **Last Updated:** 2026-03-04
+> **Last Updated:** 2026-06-16
 
 ---
 
@@ -158,7 +158,8 @@ const users = signal([
 ]);
 
 // Find by ID (supports id, _id, hash, key properties)
-const index = users.getItem(1);           // Returns index of item with id=1
+const user = users.getItem(1);            // Returns the item with id=1
+const userIndex = users.getItemIndex(1);  // Returns its index (-1 if absent)
 users.setItemProperty(1, 'name', 'Alice2');   // Set property on item with id=1
 users.replaceItem(1, newUserObject);      // Replace entire item with id=1
 users.removeItem(1);                      // Remove item with id=1

ai/skills/authoring/render-pipeline.md

@@ -23,7 +23,7 @@ Template String
      |
      v
 +-----------------+
-| TemplateCompiler |  packages/templating/src/compiler/
+| TemplateCompiler |  packages/compiler/src/
 |                  |  string -> AST (array of node objects)
 +-----------------+
          |
@@ -125,7 +125,7 @@ The engines are hot-swappable — two components on the same page can use differ
 
 ## Stage 1: TemplateCompiler
 
-`packages/templating/src/compiler/template-compiler.js`
+`packages/compiler/src/template-compiler.js`
 
 The compiler transforms a template string into an AST — a flat array of node objects. It has no knowledge of rendering, reactivity, or components.
 
@@ -567,8 +567,8 @@ lookupExpressionValue (multi-token):
 ### Key files
 
 ```
-packages/templating/src/compiler/string-scanner.js        StringScanner (char-by-char parsing)
-packages/templating/src/compiler/template-compiler.js      TemplateCompiler (string -> AST)
+packages/compiler/src/string-scanner.js                    StringScanner (char-by-char parsing)
+packages/compiler/src/template-compiler.js                 TemplateCompiler (string -> AST)
 packages/templating/src/template.js                        Template (lifecycle, state, events)
 packages/templating/src/template-helpers.js                Built-in template helpers
 

ai/skills/authoring/ssr-hydration.md

@@ -391,7 +391,7 @@ For each marker:
 
 ### The skipFirstWrite contract
 
-When debugging "my signal mutation doesn't update the DOM after hydration," name `skipFirstWrite: true` explicitly — it's the grep-able load-bearing mechanism in `packages/renderer/src/engines/native/reactive-data.js` and surfacing it lets the reader navigate the code path directly.
+When debugging "my signal mutation doesn't update the DOM after hydration," name `skipFirstWrite: true` explicitly — it's the grep-able load-bearing mechanism in `packages/renderer/src/engines/native/attribute-binding.js` and surfacing it lets the reader navigate the code path directly.
 
 Per-binding Reactions wired during hydration use `skipFirstWrite: true`:
 
@@ -592,7 +592,8 @@ packages/renderer/src/
 ├── expression-evaluator.js                           Shared expression evaluation
 ├── engines/native/server.js                          ServerRenderer — AST -> HTML string
 ├── engines/native/renderer.js                        Renderer — hydrateMarkers(), hydrateAttributes()
-├── engines/native/reactive-data.js                   bindAttribute / bindTextExpression with skipFirstWrite
+├── engines/native/attribute-binding.js               bindAttribute (attribute-position skipFirstWrite)
+│                                                      text-position hydrate lives in blocks/expression.js
 └── engines/native/blocks/
     └── each.js                                       each.hydrate (eager adoptServerItems), item proxy