@bespokeagentics/microdots-host 0.1.2 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bespokeagentics/microdots-host",
-  "version": "0.1.2",
-  "description": "MicroDots host shell — registry, loader, slot manifest and placement checks for mounting MicroDot custom elements. Raw TypeScript source; consume with Bun or Vite.",
+  "version": "0.2.0",
+  "description": "MicroDots host shell \u2014 registry, loader, slot manifest and placement checks for mounting MicroDot custom elements. Raw TypeScript source; consume with Bun or Vite.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -10,7 +10,7 @@
     "directory": "packages/microdots-host"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "main": "./src/index.ts",
   "exports": {
@@ -18,10 +18,10 @@
     "./composition": "./src/compositionSpec.ts"
   },
   "dependencies": {
-    "@bespokeagentics/microdots-authoring": "0.1.1",
-    "@bespokeagentics/microdots-element": "0.1.1"
+    "@bespokeagentics/microdots-authoring": "0.2.0",
+    "@bespokeagentics/microdots-element": "0.2.0"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.108"
+    "effect": "4.0.0-rc.112"
   }
 }

package/src/anchorMount.test.ts

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, test } from 'vitest'
+
+import { mountAtAnchor } from './anchorMount.ts'
+
+/**
+ * Anchors mount into host-owned DOM. The properties that fail silently when
+ * broken, each pinned here:
+ *
+ * 1. The container carries an id — Foldkit defects without one and
+ *    `Runtime.embed` swallows the defect (blank, clean console).
+ * 2. The anchor's own children are never touched — the anchor belongs to the
+ *    host, and `replaceChildren` on it is the loader's stated never.
+ * 3. "Not yet" resolves once the anchor appears; "not there" returns a
+ *    `timed-out` OUTCOME, never a throw and never silence.
+ *
+ * `bundleUrl` points at an already-defined tag in every case: `loadMicroDot`
+ * short-circuits when `customElements.get(tag)` exists, so no import happens
+ * and the tests stay hermetic.
+ */
+
+const TAG = 'anchor-test-dot'
+
+// Define the tag once — loadMicroDot then never fetches the bundle.
+if (customElements.get(TAG) === undefined) {
+  customElements.define(TAG, class extends HTMLElement {})
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('mountAtAnchor', () => {
+  test('mounts adjacent to an existing anchor, container id and all', async () => {
+    document.body.innerHTML =
+      '<section id="hero"><span class="kept">host copy</span></section>'
+    const outcome = await mountAtAnchor({
+      selector: '#hero',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+      attributes: { symbol: 'FOLD' },
+    })
+    expect(outcome._tag).toBe('resolved')
+    if (outcome._tag !== 'resolved') return
+    // Adjacent (default 'after'): the container is the anchor's next sibling,
+    // and the anchor's own children are untouched.
+    expect(document.querySelector('#hero + div')).toBe(outcome.container)
+    expect(document.querySelector('#hero .kept')?.textContent).toBe('host copy')
+    expect(outcome.container.id).not.toBe('')
+    expect(outcome.element.tagName.toLowerCase()).toBe(TAG)
+    expect(outcome.element.getAttribute('api-url')).toBe(
+      'http://localhost:9999',
+    )
+    expect(outcome.element.getAttribute('symbol')).toBe('FOLD')
+  })
+
+  test("'inside' appends — the anchor's existing children stay", async () => {
+    document.body.innerHTML = '<div id="panel"><p id="host-p">host</p></div>'
+    const outcome = await mountAtAnchor({
+      selector: '#panel',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+      position: 'inside',
+    })
+    expect(outcome._tag).toBe('resolved')
+    if (outcome._tag !== 'resolved') return
+    expect(outcome.container.parentElement?.id).toBe('panel')
+    expect(document.querySelector('#host-p')?.textContent).toBe('host')
+  })
+
+  test('a LATE anchor mounts when it appears — "not yet" is not "not there"', async () => {
+    const pending = mountAtAnchor({
+      selector: '#late',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+      timeoutMs: 2_000,
+    })
+    // The anchor appears after the mount was requested — the embedding-demo
+    // shape, whose whole page is written by script after load.
+    const late = document.createElement('div')
+    late.id = 'late'
+    document.body.appendChild(late)
+    const outcome = await pending
+    expect(outcome._tag).toBe('resolved')
+    if (outcome._tag !== 'resolved') return
+    expect(document.querySelector('#late + div')).toBe(outcome.container)
+  })
+
+  test('no match by the timeout returns timed-out and mounts nothing', async () => {
+    const outcome = await mountAtAnchor({
+      selector: '#never',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+      timeoutMs: 50,
+    })
+    expect(outcome._tag).toBe('timed-out')
+    if (outcome._tag !== 'timed-out') return
+    expect(outcome.selector).toBe('#never')
+    expect(document.querySelector(TAG)).toBeNull()
+  })
+
+  test('two mounts of one tag get distinct container ids', async () => {
+    document.body.innerHTML = '<div id="a"></div><div id="b"></div>'
+    const first = await mountAtAnchor({
+      selector: '#a',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+    })
+    const second = await mountAtAnchor({
+      selector: '#b',
+      tag: TAG,
+      bundleUrl: '/unused.js',
+      apiUrl: 'http://localhost:9999',
+    })
+    expect(first._tag).toBe('resolved')
+    expect(second._tag).toBe('resolved')
+    if (first._tag !== 'resolved' || second._tag !== 'resolved') return
+    expect(first.container.id).not.toBe(second.container.id)
+  })
+})

package/src/anchorMount.ts

@@ -0,0 +1,153 @@
+import { loadMicroDot, createMicroDot } from './loader.ts'
+
+/**
+ * Mounting a MicroDot at a DOM ANCHOR — a CSS selector into host-owned markup
+ * — instead of a declared slot. The Pages write-mode plan's D4; the design
+ * record is `wiki/framework/mounting/anchor-mounting-into-host-owned-dom.md`.
+ *
+ * The rules that shape this module, each with its reason:
+ *
+ * - **Resolve after paint.** The anchor is somebody else's element, typically
+ *   built by the host's own script (the embedding-demo writes its whole page
+ *   via `outerHTML` in `startHost()`), so `querySelector` before
+ *   `DOMContentLoaded` proves nothing.
+ * - **"Not yet" is not "not there".** A missing anchor gets a
+ *   `MutationObserver` until it appears or the timeout runs out. The two
+ *   outcomes are distinguishable in the return value.
+ * - **A timeout is a RETURNED outcome plus a console line, never a throw and
+ *   never silence.** A swallowed rejection here is this repo's signature
+ *   blank-with-clean-console.
+ * - **Own container, with an id.** Foldkit keys HMR preservation off the
+ *   container id and defects silently without one (`mountPoint.ts`), and the
+ *   anchor itself must never be handed to `Runtime.embed`.
+ * - **Adjacent, never inside by default — and never `replaceChildren`.** The
+ *   anchor is host-owned; `loader.ts:80-83` states the rule for slots and it
+ *   binds twice as hard for an element the host may re-render.
+ */
+
+export type AnchorMountOutcome =
+  | {
+      readonly _tag: 'resolved'
+      readonly element: HTMLElement
+      readonly container: HTMLElement
+    }
+  | {
+      readonly _tag: 'timed-out'
+      readonly selector: string
+      readonly waitedMs: number
+    }
+
+export type AnchorMountOptions = {
+  readonly selector: string
+  readonly tag: string
+  readonly bundleUrl: string
+  readonly apiUrl: string
+  readonly attributes?: Readonly<Record<string, string>>
+  /** Where the container lands relative to the anchor. Default `'after'` —
+   *  adjacent placement never disturbs the anchor's own children. */
+  readonly position?: 'before' | 'after' | 'inside'
+  /** How long to wait for a late anchor before giving up. Default 10s. */
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+/** Ids handed out so far, per tag — a counter, never a live-DOM count, so an
+ *  unmounted instance's id is never reused (the `mountPoint.ts` precedent). */
+const handedOut = new Map<string, number>()
+
+const anchorContainerId = (tag: string): string => {
+  const next = handedOut.get(tag) ?? 0
+  handedOut.set(tag, next + 1)
+  return `microdots-anchor-${tag}-${String(next)}`
+}
+
+const afterDomReady = (): Promise<void> =>
+  document.readyState === 'loading'
+    ? new Promise(resolve => {
+        document.addEventListener('DOMContentLoaded', () => resolve(), {
+          once: true,
+        })
+      })
+    : Promise.resolve()
+
+/** The anchor now, or the anchor as soon as a mutation produces one, or
+ *  `null` at the timeout. */
+const awaitAnchor = (
+  selector: string,
+  timeoutMs: number,
+): Promise<Element | null> => {
+  const immediate = document.querySelector(selector)
+  if (immediate !== null) return Promise.resolve(immediate)
+  return new Promise(resolve => {
+    const observer = new MutationObserver(() => {
+      const found = document.querySelector(selector)
+      if (found !== null) {
+        clearTimeout(timer)
+        observer.disconnect()
+        resolve(found)
+      }
+    })
+    const timer = setTimeout(() => {
+      observer.disconnect()
+      resolve(null)
+    }, timeoutMs)
+    observer.observe(document.body, { childList: true, subtree: true })
+  })
+}
+
+const placeContainer = (
+  anchor: Element,
+  container: HTMLElement,
+  position: 'before' | 'after' | 'inside',
+): void => {
+  if (position === 'inside') {
+    // Inside is APPEND — the anchor's existing children are host-owned and
+    // stay exactly where they are. Never `replaceChildren` here.
+    anchor.appendChild(container)
+    return
+  }
+  anchor.insertAdjacentElement(
+    position === 'before' ? 'beforebegin' : 'afterend',
+    container,
+  )
+}
+
+/**
+ * Resolves the selector (waiting for a late anchor), loads the bundle in
+ * parallel with the wait, then mounts the configured element inside its own
+ * id-carrying container adjacent to (or inside) the anchor.
+ */
+export const mountAtAnchor = async (
+  options: AnchorMountOptions,
+): Promise<AnchorMountOutcome> => {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const position = options.position ?? 'after'
+  const startedAt = performance.now()
+
+  // The bundle fetch does not depend on the anchor existing — start it now so
+  // a late anchor mounts fast once it appears.
+  const loading = loadMicroDot(options.bundleUrl, options.tag)
+
+  await afterDomReady()
+  const anchor = await awaitAnchor(options.selector, timeoutMs)
+  if (anchor === null) {
+    const waitedMs = Math.round(performance.now() - startedAt)
+    console.warn(
+      `mountAtAnchor: no element matched "${options.selector}" within ${String(waitedMs)}ms — <${options.tag}> not mounted`,
+    )
+    return { _tag: 'timed-out', selector: options.selector, waitedMs }
+  }
+
+  await loading
+  const element = createMicroDot(
+    options.tag,
+    options.apiUrl,
+    options.attributes ?? {},
+  )
+  const container = document.createElement('div')
+  container.id = anchorContainerId(options.tag)
+  container.appendChild(element)
+  placeContainer(anchor, container, position)
+  return { _tag: 'resolved', element, container }
+}

package/src/fillComposition.ts

@@ -83,7 +83,7 @@ export type FillCompositionFailure =
     }
 
 export class FillCompositionError extends Error {
-  readonly name = 'FillCompositionError'
+  override readonly name = 'FillCompositionError'
   /**
    * Declared and assigned, NOT a `constructor(readonly failure: …)` parameter
    * property. A parameter property is TS syntax that needs code GENERATED for

package/src/index.ts

@@ -22,6 +22,11 @@
 export {
   type MicroDotEntry,
   type MicroDotRegistry,
+  TopologyRegistryEntry,
+  bundleAlreadyDefined,
+  isAllowedBundle,
+  refusedRegistryRows,
+  resolveRegistry,
   apiUrlFor,
   findEntry,
 } from './registry.ts'
@@ -58,6 +63,7 @@ export {
  */
 export {
   type WireState,
+  ANCHOR_SLOT_ID,
   deriveWireState,
   HostTopology,
   PlacementCondition,
@@ -67,6 +73,7 @@ export {
   TopologyOverview,
   TopologyPlacement,
   TopologyRoute,
+  layoutModeOf,
   topologyRouteTable,
   Wire,
   WireEnv,
@@ -216,6 +223,45 @@ export {
   pruneGeneratedContainers,
 } from './slotDom.ts'
 
+/**
+ * Generated layout — the inversion of the rule above, for a host that
+ * OPTED IN (`layoutModeOf(topology) === 'generated'`): the data wins and
+ * `renderLayout` reconciles the page to it; `slotDom.ts` stays the
+ * authored-host fallback. `slotLayout.ts` is the one place kind→geometry
+ * lives — the values mirror the Pages canvas so both renderings of a
+ * manifest agree structurally. See
+ * `wiki/plans/active/microdots-platform-pages-generated-layout.md`.
+ */
+export {
+  type LayoutRow,
+  type StylePairs,
+  generatedSectionId,
+  layoutRows,
+  placementSpanStyle,
+  rowStyle,
+  sectionStyle,
+  slotStyle,
+} from './slotLayout.ts'
+
+export {
+  type RenderLayoutReport,
+  LAYOUT_ATTRIBUTE,
+  renderLayout,
+} from './renderLayout.ts'
+
+/**
+ * Mounting at a DOM anchor — a CSS selector into host-owned markup instead of
+ * a declared slot. Resolve-after-paint, "not yet" observed via mutations,
+ * timeout as a returned outcome, own id-carrying container, adjacent by
+ * default and never `replaceChildren`. See
+ * `wiki/framework/mounting/anchor-mounting-into-host-owned-dom.md`.
+ */
+export {
+  type AnchorMountOptions,
+  type AnchorMountOutcome,
+  mountAtAnchor,
+} from './anchorMount.ts'
+
 /**
  * Drag-resize for slots that declare a `resize` axis — the remaining half of
  * the slot-manifest generalisation in
@@ -235,9 +281,10 @@ export {
 } from './slotResize.ts'
 
 /**
- * The placement checks engine — Phase 5 work item 4: six of the spec's seven
- * checks as a pure lint over the resolution's output (check 5 defers with
- * anchors). Unverifiable checks are reported, never silently skipped.
+ * The placement checks engine — Phase 5 work item 4: the spec's seven checks
+ * as a pure lint over the resolution's output (check 5 as its unverifiable
+ * reporter only — no crawl exists). Unverifiable checks are reported, never
+ * silently skipped.
  */
 export {
   type PlacementCheckContext,
@@ -280,3 +327,9 @@ export {
   postWireTraces,
   startTracePublisher,
 } from './tracePublisher.ts'
+
+export {
+  DEFAULT_CDN_BASE_URL,
+  missingRegistryRows,
+  registryEntryFromManifest,
+} from './registryFromManifest.ts'

package/src/mountedRegistry.test.ts

@@ -32,6 +32,7 @@ const placement = (tag: string): ResolvedPlacement => ({
   values: {},
   span: Option.none(),
   order: Option.none(),
+  selector: Option.none(),
   state: 'active',
   overriddenBy: [],
 })

package/src/mounting.test.ts

@@ -182,6 +182,29 @@ describe('pendingMounts', () => {
       'winner',
     ])
   })
+
+  test('drops an anchor placement — the slot loop must never ensureSlot("@anchor")', () => {
+    const topology = topologyOf([
+      route('/home', [
+        { id: 'slotted', tag: 'promo-banner', slotId: 'hero-slot' },
+        {
+          id: 'anchored',
+          tag: 'price-ticker',
+          slotId: '@anchor',
+          selector: '#hero .cta-row',
+        },
+      ]),
+    ])
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+    // The anchor is IN the resolution — screens render it — but not in the
+    // pending mounts: a shell's slot loop feeding `@anchor` into `ensureSlot`
+    // would fabricate a `<div id="@anchor">`. Anchors mount only through
+    // `mountAtAnchor`, in a host that opts in.
+    expect(resolved.map(item => item.id)).toEqual(['slotted', 'anchored'])
+    expect(pendingMounts(resolved, new Set()).map(item => item.id)).toEqual([
+      'slotted',
+    ])
+  })
 })
 
 // The failure mode this function exists for, verbatim from the D1 extraction:

package/src/mounting.ts

@@ -1,6 +1,7 @@
 import { Array } from 'effect'
 
 import type { ResolvedPlacement } from './rules.ts'
+import { ANCHOR_SLOT_ID } from './wire.ts'
 
 /**
  * What a shell does with a resolution's output on the way to the DOM — the
@@ -39,6 +40,12 @@ import type { ResolvedPlacement } from './rules.ts'
  * matching the order the shells append in.
  *
  * Fully overridden placements are dropped first: they render for nobody.
+ *
+ * ANCHOR placements are dropped too: the slot loop's `ensureSlot` would
+ * otherwise fabricate a `<div id="@anchor">` — a lie. Anchors mount through
+ * `mountAtAnchor` in a host that opts in (the embedding-demo precedent);
+ * neither first-party shell does, and a shell that wants to must call it
+ * itself rather than have the slot loop guess.
  */
 export const pendingMounts = (
   resolved: ReadonlyArray<ResolvedPlacement>,
@@ -48,7 +55,9 @@ export const pendingMounts = (
     Array.filter(
       resolved,
       placement =>
-        placement.state !== 'overridden' && !mountedTags.has(placement.tag),
+        placement.state !== 'overridden' &&
+        placement.slotId !== ANCHOR_SLOT_ID &&
+        !mountedTags.has(placement.tag),
     ),
     (a, b) => a.tag === b.tag,
   )