@bespokeagentics/microdots-host 0.1.2 → 0.2.0

package/src/placementChecks.test.ts

@@ -37,6 +37,7 @@ const placed = (
   values: {},
   span: Option.none(),
   order: Option.none(),
+  selector: Option.none(),
   state: 'active',
   overriddenBy: [],
   ...overrides,
@@ -207,6 +208,77 @@ describe('checkPlacements — check 2: slot not in the theme', () => {
       },
     ])
   })
+
+  test('does not fire for an anchor — @anchor is the escape hatch, not a missing declaration', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', '@anchor', {
+          selector: Option.some('#hero .cta-row'),
+        }),
+      ],
+      contextOf([manifestOf('promo', ['promo-banner'])]),
+    )
+    expect(issuesFor(report, 'slot-not-in-theme')).toEqual([])
+  })
+})
+
+// The failure mode: no crawl exists, so an anchor's resolution CANNOT be
+// checked — and a screen that says nothing about it reads as green. Check 5
+// ships as a reporter only: one unverifiable entry per distinct selector,
+// never an issue, never a stored guess (the write-mode plan's D5).
+describe('checkPlacements — check 5: anchor selectors are unverifiable', () => {
+  test('reports one unverifiable entry per distinct rendered selector', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', '@anchor', {
+          selector: Option.some('#hero'),
+        }),
+        placed('p2', 'contact-form', '@anchor', {
+          selector: Option.some('#hero'),
+        }),
+        placed('p3', 'price-ticker', '@anchor', {
+          selector: Option.some('footer'),
+        }),
+      ],
+      contextOf([
+        manifestOf('promo', ['promo-banner']),
+        manifestOf('contact', ['contact-form']),
+        manifestOf('price', ['price-ticker']),
+      ]),
+    )
+    expect(
+      report.unverifiable.filter(
+        entry => entry.check === 'anchor-selector-unresolved',
+      ),
+    ).toEqual([
+      {
+        check: 'anchor-selector-unresolved',
+        reason: expect.stringContaining('"#hero"'),
+      },
+      {
+        check: 'anchor-selector-unresolved',
+        reason: expect.stringContaining('"footer"'),
+      },
+    ])
+    expect(issuesFor(report, 'anchor-selector-unresolved')).toEqual([])
+  })
+
+  test('an entirely overridden anchor reports nothing — it renders for nobody', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', '@anchor', {
+          selector: Option.some('#hero'),
+          state: 'overridden',
+        }),
+      ],
+      contextOf([manifestOf('promo', ['promo-banner'])]),
+    )
+    expect(
+      report.unverifiable.filter(
+        entry => entry.check === 'anchor-selector-unresolved',
+      ),
+    ).toEqual([])
+  })
 })
 
 // The failure mode: a manifest-required attribute nobody sets means the
@@ -367,12 +439,12 @@ describe('checkPlacements — check 6: over the page-weight budget', () => {
     // kill.
     const report = checkPlacements(
       [
-        placed('p1', 'workbench-app-list', 'hero-slot'),
+        placed('p1', 'workbench-board', 'hero-slot'),
         placed('p2', 'workbench-brief', 'side-slot'),
         placed('p3', 'wiring-canvas', 'side-slot'),
       ],
       contextOf([
-        manifestOf('workbench', ['workbench-app-list', 'workbench-brief'], {
+        manifestOf('workbench', ['workbench-board', 'workbench-brief'], {
           gzipBytes: 100 * KB,
         }),
         manifestOf('wiring', ['wiring-canvas'], { gzipBytes: 70 * KB }),
@@ -384,12 +456,12 @@ describe('checkPlacements — check 6: over the page-weight budget', () => {
   test('warns once over budget, naming the total and the largest bundle', () => {
     const report = checkPlacements(
       [
-        placed('p1', 'workbench-app-list', 'hero-slot'),
+        placed('p1', 'workbench-board', 'hero-slot'),
         placed('p2', 'workbench-brief', 'side-slot'),
         placed('p3', 'wiring-canvas', 'side-slot'),
       ],
       contextOf([
-        manifestOf('workbench', ['workbench-app-list', 'workbench-brief'], {
+        manifestOf('workbench', ['workbench-board', 'workbench-brief'], {
           gzipBytes: 100 * KB,
         }),
         manifestOf('wiring', ['wiring-canvas'], { gzipBytes: 90 * KB }),
@@ -591,3 +663,107 @@ describe('checkPlacements — the reading-B override qualifier', () => {
     ).toEqual(['loser'])
   })
 })
+
+describe('checkPlacements — check 8: over slot capacity', () => {
+  // Diagnostics, not enforcement: nothing at runtime refuses the third
+  // placement in a capacity-2 slot — the generated host stacks it — so the
+  // claim is DISAGREEMENT between the declaration and the placements, which
+  // stays true regardless of renderer behavior.
+  const capacityManifest: HostSlotManifest = {
+    theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.1' },
+    slots: [
+      { id: 'hero-slot', kind: 'band', row: 0, capacity: 2 },
+      { id: 'main-slot', kind: 'grid', row: 1 },
+    ],
+  }
+
+  test('warns once per overflowing slot, on the first placement past capacity in stacking order', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'a-view', 'hero-slot', { order: Option.some(1) }),
+        placed('p2', 'b-view', 'hero-slot', { order: Option.some(2) }),
+        placed('p3', 'c-view', 'hero-slot', { order: Option.some(3) }),
+        placed('p4', 'd-view', 'hero-slot', { order: Option.some(4) }),
+      ],
+      contextOf([], { slotManifest: capacityManifest }),
+    )
+    const issues = issuesFor(report, 'over-slot-capacity')
+    expect(issues.length).toBe(1)
+    expect(issues[0]?.placementId).toBe('p3')
+    expect(issues[0]?.severity).toBe('warning')
+    expect(issues[0]?.consequence).toContain('capacity 2')
+    expect(issues[0]?.consequence).toContain('4 placements')
+  })
+
+  test('does not fire at or under capacity, or for a capacity-less slot', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'a-view', 'hero-slot'),
+        placed('p2', 'b-view', 'hero-slot'),
+        placed('p3', 'c-view', 'main-slot'),
+        placed('p4', 'd-view', 'main-slot'),
+        placed('p5', 'e-view', 'main-slot'),
+      ],
+      contextOf([], { slotManifest: capacityManifest }),
+    )
+    expect(issuesFor(report, 'over-slot-capacity')).toEqual([])
+  })
+
+  test('stays silent with no manifest — the check-2 unverifiable entry already covers it', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'a-view', 'hero-slot'),
+        placed('p2', 'b-view', 'hero-slot'),
+        placed('p3', 'c-view', 'hero-slot'),
+      ],
+      { manifests: [], env: 'dev' },
+    )
+    expect(issuesFor(report, 'over-slot-capacity')).toEqual([])
+    expect(
+      report.unverifiable.filter(entry => entry.check === 'over-slot-capacity'),
+    ).toEqual([])
+  })
+})
+
+describe('checkPlacements — check 9: a span in a non-grid slot', () => {
+  const kindsManifest: HostSlotManifest = {
+    theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.1' },
+    slots: [
+      { id: 'hero-slot', kind: 'band', row: 0 },
+      { id: 'main-slot', kind: 'grid', row: 1 },
+    ],
+  }
+
+  test('notes a dormant span in a band slot — the legal residue of a kind edit', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'a-view', 'hero-slot', { span: Option.some(6) }),
+        placed('p2', 'b-view', 'main-slot', { span: Option.some(6) }),
+      ],
+      contextOf([], { slotManifest: kindsManifest }),
+    )
+    const issues = issuesFor(report, 'span-in-non-grid')
+    expect(issues.length).toBe(1)
+    expect(issues[0]?.placementId).toBe('p1')
+    expect(issues[0]?.severity).toBe('note')
+    expect(issues[0]?.consequence).toContain('dormant')
+  })
+
+  test('does not fire without a span, in a grid, in an undeclared slot, or with no manifest', () => {
+    const noSpan = checkPlacements(
+      [placed('p1', 'a-view', 'hero-slot')],
+      contextOf([], { slotManifest: kindsManifest }),
+    )
+    expect(issuesFor(noSpan, 'span-in-non-grid')).toEqual([])
+    const undeclared = checkPlacements(
+      [placed('p2', 'b-view', 'phantom-slot', { span: Option.some(4) })],
+      contextOf([], { slotManifest: kindsManifest }),
+    )
+    expect(issuesFor(undeclared, 'span-in-non-grid')).toEqual([])
+    const bare = checkPlacements(
+      [placed('p3', 'c-view', 'hero-slot', { span: Option.some(4) })],
+      { manifests: [], env: 'dev' },
+    )
+    expect(issuesFor(bare, 'span-in-non-grid')).toEqual([])
+  })
+})

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),