@bespokeagentics/microdots-host 0.1.2 → 0.1.3

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

package/src/wire.ts

@@ -126,11 +126,21 @@ export type PlacementCondition = typeof PlacementCondition.Type
 export const PlacementSpan = S.Literals([12, 8, 6, 4, 3])
 export type PlacementSpan = typeof PlacementSpan.Type
 
+/**
+ * The sentinel `slotId` of a placement pinned to a CSS selector in host-owned
+ * DOM instead of a declared slot. An anchor placement carries `selector`; the
+ * refinement below makes a half-anchor (either half without the other)
+ * unrepresentable, so a hand-edited file fails decode loudly and a mutator's
+ * `redecode()` refuses it as `undecodable` — never a silent half-record.
+ */
+export const ANCHOR_SLOT_ID = '@anchor'
+
 /**
  * Where one MicroDot element goes — widened in Phase 5 from `{tag, slotId}`
  * only as far as a shipping check or the reading-B resolution needs, per the
- * phase design's table (work item 2). Every new field is `S.optionalKey`,
- * because BOTH existing `host-topology.json` files must decode unchanged —
+ * phase design's table (work item 2), and again by the Pages write-mode plan
+ * (anchors: `'@anchor'` + `selector`). Every new field is `S.optionalKey`,
+ * because the existing `host-topology.json` files must decode unchanged —
  * backward compatibility is a hard requirement, pinned by the Phase-4-shaped
  * decode test in `./wire.test.ts`.
  *
@@ -145,11 +155,14 @@ export type PlacementSpan = typeof PlacementSpan.Type
  *                 three.
  * - `span`      — grid columns (grid slots only).
  * - `order`     — stacking order within the slot.
+ * - `selector`  — the CSS selector an anchor placement pins to. Present
+ *                 exactly when `slotId === ANCHOR_SLOT_ID`.
  *
- * Deliberately NOT here, with their checks: `'@anchor'` + `selector` +
- * `resolved` (check 5 needs a crawl) and `loading` (no check needs it and the
- * runtime has one strategy — a stored `loading` the loader ignores would be a
- * lie).
+ * Deliberately NOT here, with their reasons: `resolved`/`resolvedAt` (check 5
+ * needs a crawl that does not exist — an anchor's resolution is reported
+ * UNVERIFIABLE, never stored as a guess) and `loading` (no check needs it and
+ * the runtime has one strategy — a stored `loading` the loader ignores would
+ * be a lie).
  */
 export const TopologyPlacement = S.Struct({
   id: S.optionalKey(S.String),
@@ -160,7 +173,17 @@ export const TopologyPlacement = S.Struct({
   envs: S.optionalKey(S.Array(WireEnv)),
   span: S.optionalKey(PlacementSpan),
   order: S.optionalKey(S.Number),
-})
+  selector: S.optionalKey(S.String),
+}).pipe(
+  S.check(
+    S.makeFilter(
+      placement =>
+        (placement.slotId === ANCHOR_SLOT_ID) === ('selector' in placement) ||
+        `an anchor placement carries both slotId "${ANCHOR_SLOT_ID}" and a selector — never one half`,
+      { expected: 'selector present exactly when slotId is "@anchor"' },
+    ),
+  ),
+)
 export type TopologyPlacement = typeof TopologyPlacement.Type
 
 export const TopologyRoute = S.Struct({
@@ -244,9 +267,27 @@ export const TopologyHost = S.Struct({
   id: S.String,
   label: S.String,
   ownedInputs: S.Array(S.Struct({ name: S.String, type: S.String })),
+  /**
+   * Who owns this host's layout DOM. Absent means `authored` — hand-written
+   * markup wins and `slotDom.ts` only backfills missing containers. Only an
+   * explicitly `generated` host renders its slot manifest as its page
+   * structure (`renderLayout.ts`) and accepts layout writes from Pages. The
+   * marker is HOST-level, not manifest-level, because the gate must be
+   * readable when NO manifest exists: `generateLayout` targets exactly that
+   * state, and `removeLayout` returns to it (plan ruling D4,
+   * `wiki/plans/active/microdots-platform-pages-generated-layout.md`).
+   */
+  layout: S.optionalKey(S.Literals(['authored', 'generated'])),
 })
 export type TopologyHost = typeof TopologyHost.Type
 
+/** The layout-ownership seam: absent means `authored`. Every gate — the
+ *  proof host's renderer, the Pages service's layout mutators — reads the
+ *  mode through here, never `topology.host.layout` directly. */
+export const layoutModeOf = (topology: {
+  readonly host: TopologyHost
+}): 'authored' | 'generated' => topology.host.layout ?? 'authored'
+
 /**
  * A whole host, as data: who it is, where its elements go, what is wired to
  * what, and which events it merely watches (log-only taps — the demo host's

package/src/wireEngine.test.ts

@@ -614,7 +614,7 @@ describe('attachWireEngine', () => {
    * click sent paths from host A into panes rendering host B. All four wires
    * derive `live`, so the Wiring screen showed nothing wrong.
    */
-  test('two dots emitting the same event name drive only the wire whose `from` matches', () => {
+  test('two MicroDots emitting the same event name drive only the wire whose `from` matches', () => {
     const table = mount('wiring-table')
     const canvas = mount('pages-canvas')
     const inspector = mount('pages-inspector')