@bespokeagentics/microdots-host 0.1.2 → 0.1.3

package/src/placementChecks.ts

@@ -9,14 +9,17 @@ import {
 } from './rules.ts'
 import type { HostSlotManifest } from './slots.ts'
 import type { WireEnv } from './wire.ts'
+import { ANCHOR_SLOT_ID } from './wire.ts'
 
 /**
- * The placement CHECKS — six of the spec's seven, run as a pure lint engine
+ * The placement CHECKS — the spec's seven, run as a pure lint engine
  * over `resolvePlacements`' output. Phase 5 work item 4 of
  * `wiki/plans/shipped/microdots-platform-phase-5-pages-design.md`;
  * the seven checks' severities and sentences are the handoff spec's, lifted
- * verbatim where the fixture wrote them. Check 5 (anchor selector crawl) is
- * deferred with anchors.
+ * verbatim where the fixture wrote them. Check 5 (anchor selector resolution)
+ * has an id and a reporter but NO verifier: no crawl exists, so every rendered
+ * anchor is reported unverifiable — a check that cannot run is never silently
+ * green (the Pages write-mode plan's D5).
  *
  * Reading B's qualifier lands here exactly as
  * `question-does-the-override-contest-consider-condition.md` predicted: a
@@ -32,8 +35,11 @@ export type PlacementCheckId =
   | 'slot-not-in-theme'
   | 'required-attribute-unset'
   | 'mounts-twice-overlapping'
+  | 'anchor-selector-unresolved'
   | 'over-weight-budget'
   | 'placed-twice-disjoint'
+  | 'over-slot-capacity'
+  | 'span-in-non-grid'
 
 export type PlacementCheckSeverity = 'error' | 'warning' | 'note'
 
@@ -188,6 +194,9 @@ const checkSlotInTheme = (
   const theme = `${slotManifest.theme.name}@${slotManifest.theme.version}`
   const issues = Array.getSomes(
     Array.map(rendered, (placement): Option.Option<PlacementIssue> =>
+      // An anchor is deliberately OUTSIDE the theme — `@anchor` is the
+      // escape hatch, not a missing declaration. Check 5 owns anchors.
+      placement.slotId === ANCHOR_SLOT_ID ||
       Array.some(slotManifest.slots, slot => slot.id === placement.slotId)
         ? Option.none()
         : Option.some({
@@ -253,6 +262,39 @@ const checkRequiredAttributes = (
   return { issues, unverifiable }
 }
 
+/* ============================================================
+   Check 5 — anchor selector resolution. UNVERIFIABLE, deliberately.
+
+   No crawl exists, so whether a selector matches anything in the host's
+   painted DOM cannot be checked from here. The honest report is one
+   unverifiable entry per distinct selector among the rendered anchors —
+   never a green row, never a stored guess (the write-mode plan's D5).
+   The verifier lands with the crawl, under this same check id.
+   ============================================================ */
+
+const checkAnchors = (
+  rendered: ReadonlyArray<ResolvedPlacement>,
+): PlacementCheckReport => {
+  const selectors = Array.dedupe(
+    Array.getSomes(
+      Array.map(rendered, placement =>
+        placement.slotId === ANCHOR_SLOT_ID
+          ? placement.selector
+          : Option.none<string>(),
+      ),
+    ),
+  )
+  return {
+    issues: [],
+    unverifiable: selectors.map(
+      (selector): UnverifiableCheck => ({
+        check: 'anchor-selector-unresolved',
+        reason: `no crawl has run — whether "${selector}" matches anything in the host cannot be verified`,
+      }),
+    ),
+  }
+}
+
 /* ============================================================
    Checks 4 and 7 — the same dot twice on the route. Warning / note.
 
@@ -396,15 +438,95 @@ const checkWeightBudget = (
   })
 }
 
+/* ============================================================
+   Checks 8 and 9 — the generated-layout widening
+   (`wiki/plans/active/microdots-platform-pages-generated-layout.md` §E).
+   DIAGNOSTICS, not runtime enforcement: no renderer refuses the state
+   either check reports, and both claim only what a manifest can make
+   verifiable — with no manifest they are silent (the existing check-2
+   unverifiable entry already covers that state; a second entry would
+   repeat it).
+   ============================================================ */
+
+/* Check 8 — over slot capacity. Warning.
+
+   Fires ONCE per overflowing slot, on the first placement past the declared
+   capacity in stacking order. The claim is DISAGREEMENT between the
+   declaration and the placements — deliberately not "will not render", so
+   the sentence stays true whether or not any renderer ever enforces
+   capacity (today none does; the generated host stacks everything). */
+
+const checkSlotCapacity = (
+  rendered: ReadonlyArray<ResolvedPlacement>,
+  slotManifest: HostSlotManifest | undefined,
+): PlacementCheckReport => {
+  if (slotManifest === undefined) return { issues: [], unverifiable: [] }
+  const issues = Array.getSomes(
+    slotManifest.slots.map((slot): Option.Option<PlacementIssue> => {
+      if (slot.capacity === undefined) return Option.none()
+      const capacity = slot.capacity
+      const occupants = Array.sort(
+        Array.filter(rendered, placement => placement.slotId === slot.id),
+        Order.mapInput(Order.Number, (placement: ResolvedPlacement) =>
+          Option.getOrElse(placement.order, () => 0),
+        ),
+      )
+      if (occupants.length <= capacity) return Option.none()
+      const first = occupants[capacity]
+      if (first === undefined) return Option.none()
+      return Option.some({
+        check: 'over-slot-capacity',
+        severity: 'warning',
+        placementId: first.id,
+        consequence: `Slot ${slot.id} declares capacity ${String(capacity)} and ${String(occupants.length)} placements resolve into it. The declaration and the placements disagree; nothing enforces capacity at runtime, so all ${String(occupants.length)} render.`,
+        action: 'Move a placement to another slot, or raise the capacity',
+      })
+    }),
+  )
+  return { issues, unverifiable: [] }
+}
+
+/* Check 9 — a span on a placement in a non-grid slot. Note.
+
+   The legal residue of a kind edit: spans go dormant on grid→band and
+   return if the slot becomes a grid again, so this is stated as dormancy,
+   never as an error demanding cleanup. */
+
+const checkSpanInNonGrid = (
+  rendered: ReadonlyArray<ResolvedPlacement>,
+  slotManifest: HostSlotManifest | undefined,
+): PlacementCheckReport => {
+  if (slotManifest === undefined) return { issues: [], unverifiable: [] }
+  const kinds = new Map(
+    slotManifest.slots.map(slot => [slot.id, slot.kind] as const),
+  )
+  const issues = Array.getSomes(
+    Array.map(rendered, (placement): Option.Option<PlacementIssue> => {
+      if (Option.isNone(placement.span)) return Option.none()
+      const kind = kinds.get(placement.slotId)
+      if (kind === undefined || kind === 'grid') return Option.none()
+      return Option.some({
+        check: 'span-in-non-grid',
+        severity: 'note',
+        placementId: placement.id,
+        consequence: `A ${String(placement.span.value)}/12 span is set but ${placement.slotId} is a ${kind} slot, so the span is dormant. It returns the moment the slot becomes a grid again.`,
+        action: 'No action needed',
+      })
+    }),
+  )
+  return { issues, unverifiable: [] }
+}
+
 /* ============================================================
    The engine.
    ============================================================ */
 
 /**
- * Runs checks 1, 2, 3, 4, 6 and 7 over a resolution's output. Pure: same
- * inputs, same report. Placements overridden ENTIRELY are excluded before
- * any check runs — they render for nobody — while partially-overridden ones
- * are checked like any other, the reading-B qualifier.
+ * Runs all seven checks over a resolution's output — check 5 as its
+ * unverifiable reporter only. Pure: same inputs, same report. Placements
+ * overridden ENTIRELY are excluded before any check runs — they render for
+ * nobody — while partially-overridden ones are checked like any other, the
+ * reading-B qualifier.
  */
 export const checkPlacements = (
   resolved: ReadonlyArray<ResolvedPlacement>,
@@ -419,7 +541,10 @@ export const checkPlacements = (
     checkSlotInTheme(rendered, context.slotManifest),
     checkRequiredAttributes(rendered, context.manifests),
     checkTwins(rendered),
+    checkAnchors(rendered),
     checkWeightBudget(rendered, context),
+    checkSlotCapacity(rendered, context.slotManifest),
+    checkSpanInNonGrid(rendered, context.slotManifest),
   ]
   return {
     issues: Array.flatMap(reports, report => report.issues),

package/src/renderLayout.test.ts

@@ -0,0 +1,263 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { renderLayout } from './renderLayout.ts'
+import { ensureSection, ensureSlot, pruneGeneratedContainers } from './slotDom.ts'
+import { generatedSectionId } from './slotLayout.ts'
+import type { SlotSpec } from './slots.ts'
+
+/**
+ * The reconciler's contract, clause by clause — every one of these fails
+ * silently in the browser when broken: a slot div without an id renders
+ * nothing on a clean console; a rebuild instead of a reconcile restarts
+ * every mounted custom element on every poll; a prune of a non-empty slot
+ * throws away a user's mounted dot.
+ */
+
+const slot = (
+  overrides: Partial<SlotSpec> & Pick<SlotSpec, 'id'>,
+): SlotSpec => ({
+  kind: 'band',
+  row: 0,
+  ...overrides,
+})
+
+const manifestOf = (slots: ReadonlyArray<SlotSpec>): { slots: ReadonlyArray<SlotSpec> } => ({
+  slots,
+})
+
+let root: HTMLElement
+
+beforeEach(() => {
+  document.body.replaceChildren()
+  root = document.createElement('div')
+  root.id = 'generated-layout'
+  document.body.appendChild(root)
+})
+
+const MARKETING = [
+  slot({ id: 'site-header', kind: 'bar', row: 0, label: 'Header' }),
+  slot({ id: 'hero', kind: 'band', row: 1, label: 'Hero', description: 'The lead.' }),
+  slot({ id: 'sidebar', kind: 'rail', row: 2, width: '150px', label: 'Sidebar' }),
+  slot({ id: 'main', kind: 'grid', row: 2, label: 'Main' }),
+  slot({ id: 'aside', kind: 'rail', row: 2, width: '172px', label: 'Aside' }),
+]
+
+describe('renderLayout — creation', () => {
+  test('every created slot div carries its declared id — the invariant', () => {
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.created).toBe(5)
+    MARKETING.forEach(s => {
+      const div = document.getElementById(s.id)
+      expect(div).not.toBeNull()
+      expect(div?.getAttribute('data-microdots-layout')).toBe('slot')
+      expect(document.getElementById(generatedSectionId(s.id))).not.toBeNull()
+    })
+  })
+
+  test('rows group as declared: three row divs, the middle row holds rail/grid/rail', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const rows = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )
+    expect(rows.length).toBe(3)
+    const middle = rows[2]
+    expect(
+      Array.from(middle?.children ?? []).map(el => el.id),
+    ).toEqual(['section-sidebar', 'section-main', 'section-aside'])
+  })
+
+  test('label and description render in section chrome, not in the slot div', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroSection = document.getElementById('section-hero')
+    expect(heroSection?.textContent).toContain('Hero')
+    expect(heroSection?.textContent).toContain('The lead.')
+    expect(document.getElementById('hero')?.childElementCount).toBe(0)
+  })
+
+  test('geometry lands as inline styles: fixed rail width via the resize var, grid columns', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const sidebarSection = document.getElementById('section-sidebar')
+    expect(sidebarSection?.getAttribute('style')).toContain(
+      'var(--slot-size-sidebar,150px)',
+    )
+    const mainSlot = document.getElementById('main')
+    expect(mainSlot?.getAttribute('style')).toContain(
+      'repeat(12, minmax(0, 1fr))',
+    )
+  })
+
+  test('a generated host with no manifest renders an empty layout (D6)', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const report = renderLayout(manifestOf([]), root)
+    expect(report.removed).toBe(5)
+    expect(root.querySelectorAll('section').length).toBe(0)
+    expect(root.children.length).toBe(0)
+  })
+})
+
+describe('renderLayout — idempotence and reconciliation', () => {
+  test('equal input keeps node identity and reports all zeros', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroBefore = document.getElementById('section-hero')
+    const slotBefore = document.getElementById('hero')
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report).toEqual({
+      created: 0,
+      relabelled: 0,
+      moved: 0,
+      removed: 0,
+      deferred: [],
+    })
+    expect(document.getElementById('section-hero')).toBe(heroBefore)
+    expect(document.getElementById('hero')).toBe(slotBefore)
+  })
+
+  test('a copy edit reconciles textContent in place — no remount of the mounted child', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const mounted = document.createElement('div')
+    mounted.textContent = 'a mounted dot'
+    document.getElementById('hero')?.appendChild(mounted)
+
+    const edited = MARKETING.map(s =>
+      s.id === 'hero' ? { ...s, label: 'Big hero', description: 'New copy.' } : s,
+    )
+    const report = renderLayout(manifestOf(edited), root)
+    expect(report.relabelled).toBe(1)
+    expect(report.moved).toBe(0)
+    expect(document.getElementById('section-hero')?.textContent).toContain(
+      'Big hero',
+    )
+    // The mounted element is the SAME node — copy never remounts.
+    expect(document.getElementById('hero')?.firstElementChild).toBe(mounted)
+  })
+
+  test('a row move relocates only the affected section and reports it', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const heroSection = document.getElementById('section-hero')
+    const moved = MARKETING.map(s => (s.id === 'hero' ? { ...s, row: 2 } : s))
+    const report = renderLayout(manifestOf(moved), root)
+    expect(report.moved).toBe(1)
+    expect(report.created).toBe(0)
+    // Same node, new row div — the move is a reparent, not a rebuild.
+    expect(document.getElementById('section-hero')).toBe(heroSection)
+    const rows = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )
+    expect(rows[1]?.querySelector('#section-hero')).not.toBeNull()
+  })
+
+  test('an in-row order swap moves exactly one section', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const swapped = [
+      MARKETING[0],
+      MARKETING[1],
+      MARKETING[3], // main before sidebar
+      MARKETING[2],
+      MARKETING[4],
+    ].flatMap(s => (s === undefined ? [] : [s]))
+    const report = renderLayout(manifestOf(swapped), root)
+    expect(report.moved).toBe(1)
+    const middle = Array.from(root.children).filter(
+      el => el.getAttribute('data-microdots-layout') === 'row',
+    )[2]
+    expect(Array.from(middle?.children ?? []).map(el => el.id)).toEqual([
+      'section-main',
+      'section-sidebar',
+      'section-aside',
+    ])
+  })
+
+  test('a kind flip clears the stale grid properties from the slot div', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const flipped = MARKETING.map(s =>
+      s.id === 'main' ? { ...s, kind: 'band' as const } : s,
+    )
+    renderLayout(manifestOf(flipped), root)
+    const style = document.getElementById('main')?.getAttribute('style') ?? ''
+    expect(style).not.toContain('grid-template-columns')
+    expect(style).toContain('flex-direction: column')
+  })
+
+  test('a resize variable set on the section survives re-render', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const section = document.getElementById('section-sidebar')
+    section?.style.setProperty('--slot-size-sidebar', '220px')
+    renderLayout(manifestOf(MARKETING), root)
+    expect(
+      document
+        .getElementById('section-sidebar')
+        ?.style.getPropertyValue('--slot-size-sidebar'),
+    ).toBe('220px')
+  })
+})
+
+describe('renderLayout — markup wins', () => {
+  test('a slot id owned by non-layout markup is untouched and deferred, with a warning', () => {
+    const stranger = document.createElement('div')
+    stranger.id = 'hero'
+    stranger.textContent = 'hand-written'
+    document.body.appendChild(stranger)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.deferred).toContain('hero')
+    expect(report.created).toBe(4)
+    expect(document.getElementById('hero')).toBe(stranger)
+    expect(stranger.textContent).toBe('hand-written')
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  test('a section id owned by non-layout markup defers the same way', () => {
+    const stranger = document.createElement('section')
+    stranger.id = 'section-hero'
+    document.body.appendChild(stranger)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const report = renderLayout(manifestOf(MARKETING), root)
+    expect(report.deferred).toContain('hero')
+    expect(document.getElementById('section-hero')).toBe(stranger)
+    warn.mockRestore()
+  })
+})
+
+describe('renderLayout — pruning', () => {
+  test('a stale empty section is pruned; a non-empty one is deferred until unmounted', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const mounted = document.createElement('div')
+    document.getElementById('hero')?.appendChild(mounted)
+
+    const withoutHeroAndHeader = MARKETING.filter(
+      s => s.id !== 'hero' && s.id !== 'site-header',
+    )
+    const report = renderLayout(manifestOf(withoutHeroAndHeader), root)
+    // site-header (empty) pruned; hero (mounted) deferred.
+    expect(report.removed).toBe(1)
+    expect(report.deferred).toEqual(['hero'])
+    expect(document.getElementById('section-site-header')).toBeNull()
+    expect(document.getElementById('section-hero')).not.toBeNull()
+
+    // The mount loop unmounts, the next pass completes the prune.
+    mounted.remove()
+    const second = renderLayout(manifestOf(withoutHeroAndHeader), root)
+    expect(second.removed).toBe(1)
+    expect(document.getElementById('section-hero')).toBeNull()
+  })
+
+  test('pruneGeneratedContainers never deletes a declared-but-empty generated slot', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    // The slotDom pruner looks for data-generated, which layout nodes never
+    // carry — the two generation paths are provably disjoint.
+    const removed = pruneGeneratedContainers(root)
+    expect(removed).toBe(0)
+    expect(document.getElementById('hero')).not.toBeNull()
+  })
+
+  test('slotDom-generated containers and layout sections coexist', () => {
+    renderLayout(manifestOf(MARKETING), root)
+    const section = ensureSection('legacy-section', root, 'x')
+    ensureSlot('legacy-slot', section, 'x')
+    const report = renderLayout(manifestOf(MARKETING), root)
+    // The reconciler leaves slotDom's containers alone entirely.
+    expect(report).toMatchObject({ created: 0, removed: 0 })
+    expect(document.getElementById('legacy-slot')).not.toBeNull()
+  })
+})