@bespokeagentics/microdots-host 0.1.2 → 0.2.0

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')
+    })
+  })
+})

package/src/slotLayout.ts

@@ -0,0 +1,113 @@
+/**
+ * Layout GEOMETRY for a generated host — pure, no DOM.
+ *
+ * The ONE place where a slot's `kind`, `width` and a placement's `span`
+ * become CSS. The values deliberately mirror the Pages canvas so the two
+ * renderings of the same manifest agree structurally
+ * (`microdots/pages/src/canvas/app.ts` — `slotSizingClass` min-w-40/flex-1,
+ * `slotMinHeightClass` min-h-36/min-h-16, the grid-cols-12 wrapper and
+ * `spanClass`). The canvas migrating onto this module is the named follow-up
+ * of `wiki/plans/active/microdots-platform-pages-generated-layout.md`, out of
+ * scope there and here.
+ *
+ * Styles are returned as ordered `[property, value][]` pairs and applied as
+ * inline literals: a generated host must not depend on a Tailwind scanner
+ * having seen a class, and the page draws NO borders — the page is a page,
+ * the canvas draws the editor chrome. Fixed widths are expressed through
+ * `var(--slot-size-<id>, <declared>)` so `attachSlotResize` composes without
+ * either module knowing the other ran. No media queries: the flex floor is
+ * `min(160px, 100%)` so a narrow viewport compresses instead of overflowing.
+ */
+
+import type { SlotSpec } from './slots.ts'
+import { slotSizeVar } from './slotResize.ts'
+
+/** An ordered inline-style listing, applied property by property — never via
+ *  `cssText`, which would wipe `--slot-size-*` set by a resize handle. */
+export type StylePairs = ReadonlyArray<readonly [string, string]>
+
+export type LayoutRow = {
+  readonly row: number
+  readonly slots: ReadonlyArray<SlotSpec>
+}
+
+/**
+ * The declared layout: slots grouped by `row`, rows ascending, declared
+ * order within a row — the `declaredLayoutFor` contract, without the cards.
+ */
+export const layoutRows = (
+  slots: ReadonlyArray<SlotSpec>,
+): ReadonlyArray<LayoutRow> =>
+  [...new Set(slots.map(slot => slot.row))]
+    .sort((a, b) => a - b)
+    .map(row => ({ row, slots: slots.filter(slot => slot.row === row) }))
+
+/**
+ * One generated `<section>` per slot: label and description live in the
+ * section's chrome, the slot div holds ONLY mounted elements. This retires
+ * the authored hosts' "two independent lists" convention (sections and slots
+ * declared separately) on the generated path — a generated slot IS its
+ * section. Rows are chrome `div`s: no ids, never hidden by routing.
+ */
+export const generatedSectionId = (slotId: string): string =>
+  `section-${slotId}`
+
+/** A row of side-by-side slots. Mirrors the canvas row band (flex,
+ *  items-stretch, gap-2) INCLUDING its overflow rule: a row whose declared
+ *  fixed widths exceed the viewport scrolls inside its own band — the
+ *  style guide's rule for wide content — so the PAGE never scrolls
+ *  horizontally. Not a media query; the same literal styles at every
+ *  width. */
+export const rowStyle = (): StylePairs => [
+  ['display', 'flex'],
+  ['align-items', 'stretch'],
+  ['gap', '0.5rem'],
+  ['min-width', '0'],
+  ['overflow-x', 'auto'],
+]
+
+/**
+ * The section is the sized flex child. Width-less slots flex with the
+ * canvas's 160px floor (as `min(160px, 100%)` so the floor never exceeds a
+ * narrow viewport); a declared width pins the section through the resize
+ * variable so a drag handle, if ever attached, wins over the declaration.
+ */
+export const sectionStyle = (slot: SlotSpec): StylePairs =>
+  slot.width === undefined
+    ? [
+        ['flex', '1 1 0%'],
+        ['min-width', 'min(160px, 100%)'],
+      ]
+    : [
+        ['flex', 'none'],
+        // No space after the comma: happy-dom's CSS parser drops the
+        // declaration with one, and browsers accept both spellings.
+        ['width', `var(${slotSizeVar(slot.id)},${slot.width})`],
+      ]
+
+/**
+ * The slot div's interior: rails run taller than the other kinds (the
+ * canvas's min-h-36 = 9rem vs min-h-16 = 4rem); a grid slot lays its
+ * children on twelve columns (the canvas's grid-cols-12 gap-1); every other
+ * kind stacks placements vertically.
+ */
+export const slotStyle = (slot: SlotSpec): StylePairs => [
+  ['min-height', slot.kind === 'rail' ? '9rem' : '4rem'],
+  ...(slot.kind === 'grid'
+    ? ([
+        ['display', 'grid'],
+        ['grid-template-columns', 'repeat(12, minmax(0, 1fr))'],
+        ['gap', '0.25rem'],
+      ] as const)
+    : ([
+        ['display', 'flex'],
+        ['flex-direction', 'column'],
+        ['gap', '0.5rem'],
+      ] as const)),
+]
+
+/** A placement's span inside a grid slot — the canvas's `spanClass`, with
+ *  the same default of the full twelve columns. */
+export const placementSpanStyle = (span: number | undefined): StylePairs => [
+  ['grid-column', `span ${String(span ?? 12)}`],
+]

package/src/slots.test.ts

@@ -16,7 +16,7 @@ const RAW_MANIFEST = {
   slots: [
     { id: 'top-bar', kind: 'bar', row: 0 },
     { id: 'hero-band', kind: 'band', row: 1 },
-    { id: 'app-list-slot', kind: 'rail', row: 2, width: '280px' },
+    { id: 'board-slot', kind: 'rail', row: 2, width: '280px' },
     { id: 'main-grid', kind: 'grid', row: 2, capacity: 4 },
   ],
 }
@@ -79,7 +79,7 @@ describe('HostSlotManifest', () => {
       JSON.stringify({
         ...RAW_MANIFEST,
         slots: [
-          { id: 'app-list-slot', kind: 'rail', row: 2, width: '280px', resize: 'x' },
+          { id: 'board-slot', kind: 'rail', row: 2, width: '280px', resize: 'x' },
           { id: 'hero-band', kind: 'band', row: 1, resize: 'y' },
         ],
       }),
@@ -91,9 +91,43 @@ describe('HostSlotManifest', () => {
     const parsed: unknown = JSON.parse(
       JSON.stringify({
         theme: RAW_MANIFEST.theme,
-        slots: [{ id: 'app-list-slot', kind: 'rail', row: 2, resize: 'both' }],
+        slots: [{ id: 'board-slot', kind: 'rail', row: 2, resize: 'both' }],
       }),
     )
     expect(Option.isNone(decodeManifest(parsed))).toBe(true)
   })
+
+  // The generated-layout widening: `label`/`description` are explicit
+  // human-authored copy (never tag-inferred), and a pre-widening manifest
+  // must decode byte-identically — the hard sequencing gate of
+  // `wiki/plans/active/microdots-platform-pages-generated-layout.md` §A.
+  test('decodes label and description without inventing either', () => {
+    const parsed: unknown = JSON.parse(
+      JSON.stringify({
+        ...RAW_MANIFEST,
+        slots: [
+          {
+            id: 'hero',
+            kind: 'band',
+            row: 1,
+            label: 'Hero',
+            description: 'The lead message.',
+          },
+          { id: 'main', kind: 'grid', row: 2, label: 'Main' },
+        ],
+      }),
+    )
+    expect(decodeManifest(parsed)).toEqual(Option.some(parsed))
+  })
+
+  test('absent label and description stay absent — copy is authored, never defaulted', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(RAW_MANIFEST))
+    const decoded = decodeManifest(parsed)
+    expect(Option.isSome(decoded)).toBe(true)
+    if (Option.isSome(decoded)) {
+      const first = decoded.value.slots[0]
+      expect(first !== undefined && 'label' in first).toBe(false)
+      expect(first !== undefined && 'description' in first).toBe(false)
+    }
+  })
 })

package/src/slots.ts

@@ -43,14 +43,23 @@ export type SlotResizeAxis = typeof SlotResizeAxis.Type
  * sharing a row sit side by side (the fixture's sidebar / main / aside).
  * `width` is a CSS length for a fixed `rail` (`'280px'`); `capacity` is how
  * many placements the slot is meant to hold. `resize` is the drag axis, if
- * any. All three of those are `optionalKey` (not `optional`) so the decoded
+ * any. All optionals are `optionalKey` (not `optional`) so the decoded
  * Type is exact-optional under `exactOptionalPropertyTypes`, matching the
  * rest of the topology schemas.
+ *
+ * `label` and `description` are EXPLICIT human-authored copy, written in the
+ * Pages inspector — the resolution of
+ * `wiki/framework/composition/gap-a-generated-section-has-no-copy-to-render.md`
+ * by that page's own proposed remedy. Copy is never inferred from a tag, a
+ * placement, or a storage key; absent means nobody has written any yet, and a
+ * generated section renders without it rather than inventing some.
  */
 export const SlotSpec = S.Struct({
   id: S.String,
   kind: SlotKind,
   row: S.Number,
+  label: S.optionalKey(S.String),
+  description: S.optionalKey(S.String),
   width: S.optionalKey(S.String),
   capacity: S.optionalKey(S.Number),
   resize: S.optionalKey(SlotResizeAxis),

package/src/wire.test.ts

@@ -14,6 +14,7 @@ import {
   TopologyPlacement,
   type Wire,
   deriveWireState,
+  layoutModeOf,
   topologyRouteTable,
 } from './wire.ts'
 
@@ -554,6 +555,13 @@ describe('the shipped host-topology.json files', () => {
     const parsed = topologyOnDisk('../../../apps/platform/host-topology.json')
     expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
   })
+
+  test('the embedding-demo topology still decodes, unchanged — the anchor host', () => {
+    const parsed = topologyOnDisk(
+      '../../../apps/embedding-demo/host-topology.json',
+    )
+    expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
+  })
 })
 
 const decodePlacement = S.decodeUnknownOption(TopologyPlacement)
@@ -592,6 +600,41 @@ describe('TopologyPlacement — the Phase-5 widening', () => {
   })
 })
 
+// The failure mode: a hand-edited half-anchor — a selector on a slot
+// placement, or `@anchor` with no selector — decoding fine and rendering as
+// whichever half a reader happens to trust. The refinement makes the
+// half-record unrepresentable, so it dies at decode and a mutator's
+// `redecode()` refuses it as `undecodable`.
+describe('TopologyPlacement — anchors (the write-mode widening)', () => {
+  const ANCHOR_PLACEMENT = {
+    id: 'emb-readout',
+    tag: 'readout-view',
+    slotId: '@anchor',
+    selector: '#widget-slot',
+    envs: ['dev'],
+  }
+
+  test('an anchor placement round-trips decode → encode byte-identically', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(ANCHOR_PLACEMENT))
+    expect(Option.map(decodePlacement(parsed), encodePlacement)).toEqual(
+      Option.some(parsed),
+    )
+  })
+
+  test('rejects @anchor without a selector', () => {
+    const { selector: _selector, ...withoutSelector } = ANCHOR_PLACEMENT
+    const parsed: unknown = JSON.parse(JSON.stringify(withoutSelector))
+    expect(Option.isNone(decodePlacement(parsed))).toBe(true)
+  })
+
+  test('rejects a selector on a slot placement', () => {
+    const parsed: unknown = JSON.parse(
+      JSON.stringify({ ...ANCHOR_PLACEMENT, slotId: 'hero-slot' }),
+    )
+    expect(Option.isNone(decodePlacement(parsed))).toBe(true)
+  })
+})
+
 // The failure mode: `rules` and `slotManifest` are the Phase-5 keys the
 // Pages screen and the resolution read — a topology carrying all three rule
 // kinds that fails to decode is a platform host that never starts.
@@ -631,3 +674,40 @@ describe('HostTopology — the Phase-5 keys', () => {
     expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
   })
 })
+
+// The generated-layout opt-in (ruling D4): host-level, absent = authored.
+// The accessor is THE seam every gate reads — a topology written before the
+// key existed must behave exactly as an authored host.
+describe('layoutModeOf', () => {
+  test('absent layout key means authored', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(RAW_TOPOLOGY))
+    const decoded = decodeTopology(parsed)
+    expect(Option.isSome(decoded)).toBe(true)
+    if (Option.isSome(decoded)) {
+      expect('layout' in decoded.value.host).toBe(false)
+      expect(layoutModeOf(decoded.value)).toBe('authored')
+    }
+  })
+
+  test('an explicitly generated host decodes unchanged and reads generated', () => {
+    const raw = {
+      ...RAW_TOPOLOGY,
+      host: { ...RAW_TOPOLOGY.host, layout: 'generated' },
+    }
+    const parsed: unknown = JSON.parse(JSON.stringify(raw))
+    const decoded = decodeTopology(parsed)
+    expect(decoded).toEqual(Option.some(parsed))
+    if (Option.isSome(decoded)) {
+      expect(layoutModeOf(decoded.value)).toBe('generated')
+    }
+  })
+
+  test('rejects a layout value that is not authored or generated', () => {
+    const raw = {
+      ...RAW_TOPOLOGY,
+      host: { ...RAW_TOPOLOGY.host, layout: 'freeform' },
+    }
+    const parsed: unknown = JSON.parse(JSON.stringify(raw))
+    expect(Option.isNone(decodeTopology(parsed))).toBe(true)
+  })
+})