@bespokeagentics/microdots-host 0.1.2 → 0.1.3

package/src/renderLayout.ts

@@ -0,0 +1,345 @@
+/**
+ * The generated-layout DOM reconciler — a manifest rendered AS the page.
+ *
+ * `slotDom.ts` is the authored-host fallback: markup wins, generation only
+ * backfills. This module is the inversion for a host that opted in
+ * (`layoutModeOf(topology) === 'generated'`): the DATA wins, and the DOM
+ * under `generatedRoot` is reconciled to match it — created, relabelled,
+ * moved and pruned in place rather than rebuilt, because rebuilding remounts
+ * every custom element on every poll.
+ *
+ * The contract, clause by clause (each one a test in
+ * `renderLayout.test.ts`):
+ *
+ * - Every created slot div receives its declared `id` unconditionally — the
+ *   repo's single most expensive failure is a mount container without one
+ *   (see `wiki/patterns-and-traps/mount-container-needs-an-id.md`).
+ * - Idempotent: equal input keeps node identity and reports all zeros.
+ * - An id already owned by non-layout markup is never touched: the slot is
+ *   `deferred` with a warning. Markup wins even in generated mode.
+ * - Label/description changes reconcile via `textContent` in place — copy
+ *   edits never remount a mounted dot.
+ * - A section moves only when its row or in-row order actually differs; a
+ *   structural move carries its mounted children with it, which restarts
+ *   them (ruling D11 — accepted v1 semantics, minimized here).
+ * - A stale section is pruned only while its slot div is EMPTY; a non-empty
+ *   one is `deferred` — the mount loop unmounts first, the next pass prunes.
+ * - Style application sets and removes only this module's own properties,
+ *   never `--slot-size-*` (a resize handle's writes survive every pass).
+ *
+ * Rows are unkeyed positional chrome; sections are keyed by slot id. The
+ * marker attribute is distinct from `slotDom.ts`'s `data-generated` so
+ * `pruneGeneratedContainers` provably never deletes a declared-but-empty
+ * generated slot.
+ */
+
+import type { SlotSpec } from './slots.ts'
+import {
+  generatedSectionId,
+  layoutRows,
+  rowStyle,
+  sectionStyle,
+  slotStyle,
+  type StylePairs,
+} from './slotLayout.ts'
+
+/** What a generated node IS: `row` and `chrome` are unkeyed structure,
+ *  `section` and `slot` are keyed by the slot's id. */
+export const LAYOUT_ATTRIBUTE = 'data-microdots-layout'
+
+export type RenderLayoutReport = {
+  readonly created: number
+  readonly relabelled: number
+  readonly moved: number
+  readonly removed: number
+  /** Slot ids left alone this pass: id collisions with non-layout markup,
+   *  and stale sections still holding mounted elements. */
+  readonly deferred: ReadonlyArray<string>
+}
+
+/** Every property either style function may emit — the removal catalog, so a
+ *  kind flip (grid → band) clears `grid-template-columns` instead of leaving
+ *  it to fight the new `display`. Custom properties are deliberately outside
+ *  the catalog: `--slot-size-*` belongs to `attachSlotResize`. */
+const SECTION_STYLE_PROPERTIES = [
+  'display',
+  'flex-direction',
+  'flex',
+  'min-width',
+  'width',
+  'gap',
+] as const
+const SLOT_STYLE_PROPERTIES = [
+  'min-height',
+  'display',
+  'grid-template-columns',
+  'gap',
+  'flex-direction',
+] as const
+
+const applyStyle = (
+  element: HTMLElement,
+  pairs: StylePairs,
+  catalog: ReadonlyArray<string>,
+): void => {
+  const declared = new Set(pairs.map(([property]) => property))
+  catalog.forEach(property => {
+    if (!declared.has(property)) element.style.removeProperty(property)
+  })
+  pairs.forEach(([property, value]) =>
+    element.style.setProperty(property, value),
+  )
+}
+
+const layoutRole = (node: Element): string | null =>
+  node.getAttribute(LAYOUT_ATTRIBUTE)
+
+/** The section's inner arrangement: chrome above the slot, stacked. */
+const sectionInnerStyle: StylePairs = [
+  ['display', 'flex'],
+  ['flex-direction', 'column'],
+  ['gap', '0.5rem'],
+]
+
+const buildSection = (slot: SlotSpec): HTMLElement => {
+  const section = document.createElement('section')
+  section.id = generatedSectionId(slot.id)
+  section.setAttribute(LAYOUT_ATTRIBUTE, 'section')
+
+  const chrome = document.createElement('div')
+  chrome.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  const label = document.createElement('div')
+  label.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  label.style.setProperty('font-weight', '600')
+  label.textContent = slot.label ?? ''
+  const description = document.createElement('div')
+  description.setAttribute(LAYOUT_ATTRIBUTE, 'chrome')
+  description.style.setProperty('opacity', '0.7')
+  description.textContent = slot.description ?? ''
+  chrome.appendChild(label)
+  chrome.appendChild(description)
+
+  const slotDiv = document.createElement('div')
+  // Never omit, never rename, never defer to a caller: a mount container
+  // without an id is the silent failure this repo has paid for the most.
+  slotDiv.id = slot.id
+  slotDiv.setAttribute(LAYOUT_ATTRIBUTE, 'slot')
+
+  section.appendChild(chrome)
+  section.appendChild(slotDiv)
+  return section
+}
+
+const chromeTexts = (
+  section: HTMLElement,
+): { label: Element; description: Element } | null => {
+  const chrome = Array.from(section.children).find(
+    child => layoutRole(child) === 'chrome',
+  )
+  if (chrome === undefined) return null
+  const label = chrome.children[0]
+  const description = chrome.children[1]
+  if (label === undefined || description === undefined) return null
+  return { label, description }
+}
+
+const slotDivOf = (section: HTMLElement): HTMLElement | null => {
+  const found = Array.from(section.children).find(
+    child => layoutRole(child) === 'slot',
+  )
+  return found instanceof HTMLElement ? found : null
+}
+
+/**
+ * Reconcile the DOM under `generatedRoot` to the manifest. Only the theme's
+ * `slots` matter to geometry, so the parameter is exactly that slice — a
+ * generated host with NO manifest passes `{ slots: [] }` and gets the legal
+ * "opted in, nothing declared" empty layout (ruling D6).
+ */
+export const renderLayout = (
+  manifest: { readonly slots: ReadonlyArray<SlotSpec> },
+  generatedRoot: HTMLElement,
+): RenderLayoutReport => {
+  const rows = layoutRows(manifest.slots)
+  let created = 0
+  let relabelled = 0
+  let moved = 0
+  let removed = 0
+  const deferred: string[] = []
+
+  // Row chrome is unkeyed, but reuse is by MAJORITY, not position: each
+  // declared row claims the existing row div already holding most of its
+  // sections, so a row merging away moves the one section that changed
+  // rather than reparenting (and remounting) every section below it.
+  const existingRowDivs = Array.from(generatedRoot.children).filter(
+    child => layoutRole(child) === 'row',
+  )
+  const claimed = new Set<Element>()
+  const claims = rows.map(row => {
+    const counts = new Map<Element, number>()
+    row.slots.forEach(rowSlot => {
+      const section = document.getElementById(generatedSectionId(rowSlot.id))
+      if (section === null || layoutRole(section) !== 'section') return
+      const parent = section.parentElement
+      if (
+        parent === null ||
+        layoutRole(parent) !== 'row' ||
+        parent.parentElement !== generatedRoot ||
+        claimed.has(parent)
+      )
+        return
+      counts.set(parent, (counts.get(parent) ?? 0) + 1)
+    })
+    const best = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]
+    if (best === undefined) return null
+    claimed.add(best[0])
+    return best[0]
+  })
+  const unclaimed = existingRowDivs.filter(div => !claimed.has(div))
+  const rowDivs = claims.map(claim => {
+    if (claim !== null) return claim
+    const reuse = unclaimed.shift()
+    if (reuse !== undefined) {
+      claimed.add(reuse)
+      return reuse
+    }
+    const rowDiv = document.createElement('div')
+    rowDiv.setAttribute(LAYOUT_ATTRIBUTE, 'row')
+    generatedRoot.appendChild(rowDiv)
+    return rowDiv
+  })
+  // Row divs must appear top-to-bottom in declared-row order; reorder with
+  // the same skip-the-strangers cursor the sections use below.
+  const rowDivSet = new Set(rowDivs)
+  let rowCursor: ChildNode | null = generatedRoot.firstChild
+  rowDivs.forEach(rowDiv => {
+    while (
+      rowCursor !== null &&
+      rowCursor !== rowDiv &&
+      !(rowCursor instanceof Element && rowDivSet.has(rowCursor))
+    ) {
+      rowCursor = rowCursor.nextSibling
+    }
+    if (rowCursor === rowDiv) {
+      rowCursor = rowCursor.nextSibling
+    } else {
+      generatedRoot.insertBefore(rowDiv, rowCursor)
+    }
+  })
+  rowDivs.forEach(rowDiv => {
+    if (rowDiv instanceof HTMLElement) applyStyle(rowDiv, rowStyle(), [])
+  })
+
+  const desiredSectionIds = new Set(
+    manifest.slots.map(slot => generatedSectionId(slot.id)),
+  )
+
+  rows.forEach((row, rowIndex) => {
+    const rowDiv = rowDivs[rowIndex]
+    if (!(rowDiv instanceof HTMLElement)) return
+
+    // Resolve or build each desired section, deferring on foreign ids.
+    const desired = row.slots.flatMap(slot => {
+      const sectionId = generatedSectionId(slot.id)
+      const existingSection = document.getElementById(sectionId)
+      if (existingSection !== null && layoutRole(existingSection) !== 'section') {
+        console.warn(
+          `[renderLayout] id "${sectionId}" is owned by non-layout markup — leaving it alone (markup wins)`,
+        )
+        deferred.push(slot.id)
+        return []
+      }
+      if (existingSection === null) {
+        const slotCollision = document.getElementById(slot.id)
+        if (slotCollision !== null && layoutRole(slotCollision) !== 'slot') {
+          console.warn(
+            `[renderLayout] slot id "${slot.id}" is owned by non-layout markup — leaving it alone (markup wins)`,
+          )
+          deferred.push(slot.id)
+          return []
+        }
+        const built = buildSection(slot)
+        created += 1
+        return [{ slot, section: built, isNew: true }]
+      }
+      // Copy reconciles in place — textContent only, never a rebuild.
+      const texts = chromeTexts(existingSection)
+      if (texts !== null) {
+        const nextLabel = slot.label ?? ''
+        const nextDescription = slot.description ?? ''
+        let changed = false
+        if (texts.label.textContent !== nextLabel) {
+          texts.label.textContent = nextLabel
+          changed = true
+        }
+        if (texts.description.textContent !== nextDescription) {
+          texts.description.textContent = nextDescription
+          changed = true
+        }
+        if (changed) relabelled += 1
+      }
+      return [{ slot, section: existingSection, isNew: false }]
+    })
+
+    const desiredSet = new Set<Element>(desired.map(entry => entry.section))
+
+    // Minimal-move ordering: advance a cursor past nodes that are staying
+    // put (deferred strangers, stale sections awaiting their prune); insert
+    // only the sections whose row or order actually differs.
+    let cursor: ChildNode | null = rowDiv.firstChild
+    desired.forEach(entry => {
+      while (
+        cursor !== null &&
+        cursor !== entry.section &&
+        !(cursor instanceof Element && desiredSet.has(cursor))
+      ) {
+        cursor = cursor.nextSibling
+      }
+      if (cursor === entry.section) {
+        cursor = cursor.nextSibling
+      } else {
+        rowDiv.insertBefore(entry.section, cursor)
+        if (!entry.isNew) moved += 1
+      }
+      if (entry.section instanceof HTMLElement) {
+        applyStyle(entry.section, [
+          ...sectionInnerStyle,
+          ...sectionStyle(entry.slot),
+        ], SECTION_STYLE_PROPERTIES)
+        const slotDiv = slotDivOf(entry.section)
+        if (slotDiv !== null) {
+          applyStyle(slotDiv, slotStyle(entry.slot), SLOT_STYLE_PROPERTIES)
+        }
+      }
+    })
+  })
+
+  // Prune stale sections — but ONLY once their slot div is empty. A section
+  // still holding a mounted element is deferred: the caller's mount loop
+  // unmounts on its own schedule, and the next pass completes the prune.
+  Array.from(
+    generatedRoot.querySelectorAll(`section[${LAYOUT_ATTRIBUTE}="section"]`),
+  ).forEach(section => {
+    if (desiredSectionIds.has(section.id)) return
+    if (!(section instanceof HTMLElement)) return
+    const slotDiv = slotDivOf(section)
+    if (slotDiv !== null && slotDiv.childElementCount > 0) {
+      deferred.push(slotDiv.id)
+      return
+    }
+    section.remove()
+    removed += 1
+  })
+
+  // Stale row chrome goes once it is empty; rows are structure, not
+  // content, so an unclaimed div holding a deferred section stays put.
+  Array.from(generatedRoot.children)
+    .filter(child => layoutRole(child) === 'row')
+    .forEach(rowDiv => {
+      if (!rowDivSet.has(rowDiv) && rowDiv.childElementCount === 0) {
+        rowDiv.remove()
+      }
+    })
+
+  return { created, relabelled, moved, removed, deferred }
+}

package/src/rules.test.ts

@@ -139,6 +139,7 @@ describe('resolvePlacements', () => {
         values: {},
         span: Option.none(),
         order: Option.none(),
+        selector: Option.none(),
         state: 'active',
         overriddenBy: [],
       },
@@ -595,4 +596,88 @@ describe('resolvePlacements', () => {
       resolvePlacements(topology, '/home', 'dev').map(item => item.state),
     ).toEqual(['active', 'active'])
   })
+
+  // The failure mode: the contest keys on `(tag, slotId)`, and every anchor
+  // shares the one sentinel slotId — without the selector qualifier, a route
+  // anchoring a tag at one selector would silently override a rule anchoring
+  // the same tag somewhere else on the page entirely.
+  describe('anchors', () => {
+    test('the selector surfaces on the resolved placement', () => {
+      const topology = topologyOf([
+        route('/home', [
+          {
+            id: 'a1',
+            tag: 'promo-banner',
+            slotId: '@anchor',
+            selector: '#hero .cta-row',
+          },
+        ]),
+      ])
+      expect(
+        resolvePlacements(topology, '/home', 'dev').map(item => item.selector),
+      ).toEqual([Option.some('#hero .cta-row')])
+    })
+
+    test('same tag at the SAME selector contests across layers', () => {
+      const topology = topologyOf(
+        [
+          route('/home', [
+            {
+              id: 'winner',
+              tag: 'promo-banner',
+              slotId: '@anchor',
+              selector: '#hero',
+            },
+          ]),
+        ],
+        [
+          patternRule('r1', '/*', [
+            {
+              id: 'loser',
+              tag: 'promo-banner',
+              slotId: '@anchor',
+              selector: '#hero',
+            },
+          ]),
+        ],
+      )
+      expect(
+        resolvePlacements(topology, '/home', 'dev').map(item => ({
+          id: item.id,
+          state: item.state,
+        })),
+      ).toEqual([
+        { id: 'loser', state: 'overridden' },
+        { id: 'winner', state: 'active' },
+      ])
+    })
+
+    test('same tag at DIFFERENT selectors never contests — different places', () => {
+      const topology = topologyOf(
+        [
+          route('/home', [
+            {
+              id: 'route-anchor',
+              tag: 'promo-banner',
+              slotId: '@anchor',
+              selector: '#hero',
+            },
+          ]),
+        ],
+        [
+          patternRule('r1', '/*', [
+            {
+              id: 'rule-anchor',
+              tag: 'promo-banner',
+              slotId: '@anchor',
+              selector: 'footer',
+            },
+          ]),
+        ],
+      )
+      expect(
+        resolvePlacements(topology, '/home', 'dev').map(item => item.state),
+      ).toEqual(['active', 'active'])
+    })
+  })
 })

package/src/rules.ts

@@ -8,6 +8,7 @@ import type {
   TopologyPlacement,
   WireEnv,
 } from './wire.ts'
+import { ANCHOR_SLOT_ID } from './wire.ts'
 
 /**
  * Rules, THE matcher, and the reading-B resolution — Phase 5 work item 3 of
@@ -228,6 +229,9 @@ export type ResolvedPlacement = {
   readonly values: Readonly<Record<string, string>>
   readonly span: Option.Option<PlacementSpan>
   readonly order: Option.Option<number>
+  /** The CSS selector of an anchor placement (`slotId === ANCHOR_SLOT_ID`).
+   *  `None` for every slot-placed record. */
+  readonly selector: Option.Option<string>
   readonly state: ResolvedState
   readonly overriddenBy: ReadonlyArray<PlacementOverride>
 }
@@ -413,6 +417,10 @@ export const resolvePlacements = (
         other.layer > item.layer &&
         other.placement.tag === item.placement.tag &&
         other.placement.slotId === item.placement.slotId &&
+        // Two anchors of one tag at DIFFERENT selectors are different places —
+        // they never contest. Slot-placed records are unaffected.
+        (item.placement.slotId !== ANCHOR_SLOT_ID ||
+          other.placement.selector === item.placement.selector) &&
         conditionsOverlap(other.condition, item.condition)
           ? Option.some({
               by: other.source,
@@ -441,6 +449,7 @@ export const resolvePlacements = (
       values: item.placement.values ?? {},
       span: Option.fromNullishOr(item.placement.span),
       order: Option.fromNullishOr(item.placement.order),
+      selector: Option.fromNullishOr(item.placement.selector),
       state,
       overriddenBy,
     }

package/src/slotLayout.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'vitest'
+
+import {
+  generatedSectionId,
+  layoutRows,
+  placementSpanStyle,
+  rowStyle,
+  sectionStyle,
+  slotStyle,
+} from './slotLayout.ts'
+import type { SlotSpec } from './slots.ts'
+
+/**
+ * The geometry module is the ONE place kind→CSS lives, and its numbers must
+ * mirror the Pages canvas (`microdots/pages/src/canvas/app.ts`): the 160px
+ * flex floor, the 9rem/4rem rail min-heights, the twelve-column grid, the
+ * span default of 12. A second set of numbers anywhere else is the drift
+ * risk R7 of the plan.
+ */
+
+const slot = (overrides: Partial<SlotSpec> & Pick<SlotSpec, 'id'>): SlotSpec => ({
+  kind: 'band',
+  row: 0,
+  ...overrides,
+})
+
+describe('layoutRows', () => {
+  test('groups by row ascending, declared order within a row', () => {
+    const slots = [
+      slot({ id: 'aside', kind: 'rail', row: 2 }),
+      slot({ id: 'header', kind: 'bar', row: 0 }),
+      slot({ id: 'sidebar', kind: 'rail', row: 2 }),
+      slot({ id: 'hero', kind: 'band', row: 1 }),
+    ]
+    const rows = layoutRows(slots)
+    expect(rows.map(r => r.row)).toEqual([0, 1, 2])
+    // Declared order within row 2: aside first — it appeared first.
+    expect(rows[2]?.slots.map(s => s.id)).toEqual(['aside', 'sidebar'])
+  })
+
+  test('an empty manifest yields no rows', () => {
+    expect(layoutRows([])).toEqual([])
+  })
+
+  test('non-contiguous row numbers still group — the renderer is positional', () => {
+    const rows = layoutRows([
+      slot({ id: 'a', row: 5 }),
+      slot({ id: 'b', row: 2 }),
+    ])
+    expect(rows.map(r => r.row)).toEqual([2, 5])
+  })
+})
+
+describe('generatedSectionId', () => {
+  test('prefixes the slot id', () => {
+    expect(generatedSectionId('hero')).toBe('section-hero')
+  })
+})
+
+describe('the style pair functions', () => {
+  test('rowStyle is a flex band that scrolls inside itself when over-wide', () => {
+    expect(rowStyle()).toEqual([
+      ['display', 'flex'],
+      ['align-items', 'stretch'],
+      ['gap', '0.5rem'],
+      ['min-width', '0'],
+      ['overflow-x', 'auto'],
+    ])
+  })
+
+  test('a width-less slot flexes with the canvas 160px floor, viewport-capped', () => {
+    expect(sectionStyle(slot({ id: 'main', kind: 'grid' }))).toEqual([
+      ['flex', '1 1 0%'],
+      ['min-width', 'min(160px, 100%)'],
+    ])
+  })
+
+  test('a declared width pins through the resize variable so attachSlotResize composes', () => {
+    expect(sectionStyle(slot({ id: 'sidebar', kind: 'rail', width: '150px' }))).toEqual([
+      ['flex', 'none'],
+      ['width', 'var(--slot-size-sidebar,150px)'],
+    ])
+  })
+
+  test('rails run taller; other kinds stack at the 4rem floor', () => {
+    expect(slotStyle(slot({ id: 'r', kind: 'rail' }))[0]).toEqual([
+      'min-height',
+      '9rem',
+    ])
+    expect(slotStyle(slot({ id: 'b', kind: 'bar' }))[0]).toEqual([
+      'min-height',
+      '4rem',
+    ])
+  })
+
+  test('a grid slot lays twelve columns; other kinds stack vertically', () => {
+    const grid = slotStyle(slot({ id: 'main', kind: 'grid' }))
+    expect(grid).toContainEqual(['display', 'grid'])
+    expect(grid).toContainEqual([
+      'grid-template-columns',
+      'repeat(12, minmax(0, 1fr))',
+    ])
+    const band = slotStyle(slot({ id: 'hero', kind: 'band' }))
+    expect(band).toContainEqual(['display', 'flex'])
+    expect(band).toContainEqual(['flex-direction', 'column'])
+  })
+
+  test('placementSpanStyle defaults to the full twelve columns', () => {
+    expect(placementSpanStyle(4)).toEqual([['grid-column', 'span 4']])
+    expect(placementSpanStyle(undefined)).toEqual([['grid-column', 'span 12']])
+  })
+
+  test('no function emits a media query anywhere', () => {
+    const all = [
+      ...rowStyle(),
+      ...sectionStyle(slot({ id: 'a' })),
+      ...sectionStyle(slot({ id: 'b', width: '200px' })),
+      ...slotStyle(slot({ id: 'c', kind: 'grid' })),
+      ...slotStyle(slot({ id: 'd', kind: 'rail' })),
+      ...placementSpanStyle(6),
+    ]
+    all.forEach(([property, value]) => {
+      expect(property).not.toContain('@media')
+      expect(value).not.toContain('@media')
+    })
+  })
+})