@bespokeagentics/microdots-host 0.1.0

package/src/mounting.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from 'vitest'
+
+import { mountOverridesFor, pendingMounts } from './mounting.ts'
+import { resolvePlacements } from './rules.ts'
+import type {
+  HostTopology,
+  RouteRule,
+  TopologyPlacement,
+  TopologyRoute,
+} from './wire.ts'
+
+/* ============================================================
+   Fixtures. `pendingMounts` is fed from `resolvePlacements` in both shells,
+   so it is fed from `resolvePlacements` here too — a hand-built
+   `ResolvedPlacement[]` would let the two drift and would not reproduce the
+   shapes that actually collide.
+   ============================================================ */
+
+const route = (
+  path: string,
+  mounts: ReadonlyArray<TopologyPlacement>,
+): TopologyRoute => ({
+  path,
+  label: path,
+  title: path,
+  sectionIds: [],
+  mounts,
+})
+
+const topologyOf = (
+  routes: readonly [TopologyRoute, ...Array<TopologyRoute>],
+  rules?: ReadonlyArray<RouteRule>,
+): HostTopology => ({
+  host: { id: 'test-host', label: 'Test host', ownedInputs: [] },
+  routes,
+  ...(rules === undefined ? {} : { rules }),
+  wires: [],
+  watch: [],
+})
+
+const patternRule = (
+  id: string,
+  pattern: string,
+  placements: ReadonlyArray<TopologyPlacement>,
+): RouteRule => ({
+  id,
+  kind: 'pattern',
+  label: `Rule ${id}`,
+  pattern,
+  placements,
+})
+
+/** What the demo host's `resolvedMountsFor` does for its DERIVED overview
+ *  route: the route has no topology entry, so its resolution is the union of
+ *  every component route's resolution. */
+const overviewUnion = (topology: HostTopology) =>
+  topology.routes.flatMap(candidate =>
+    resolvePlacements(topology, candidate.path, 'dev'),
+  )
+
+// The failure mode: both shells used to write
+// `Array.filter(resolved, p => !mountedTags.has(p.tag))` and latch the tags in
+// a SEPARATE `forEach` afterwards. `filter` finishes its whole pass before
+// `forEach` runs, so nothing a filtered entry latches can be seen by its own
+// twin — one tag resolved twice survives twice and is appended to its slot
+// twice. Two live elements on one page, both polling, both answering brokered
+// writes, and a console with nothing in it.
+describe('pendingMounts', () => {
+  test('a tag resolved twice in one list is pending ONCE', () => {
+    const topology = topologyOf([
+      route('/price', [
+        { tag: 'price-ticker', slotId: 'price-slot' },
+        { tag: 'price-ticker', slotId: 'compare-slot' },
+      ]),
+    ])
+    const resolved = resolvePlacements(topology, '/price', 'dev')
+
+    expect(resolved.length).toBe(2)
+    expect(pendingMounts(resolved, new Set()).map(item => item.slotId)).toEqual(
+      ['price-slot'],
+    )
+  })
+
+  test('the demo-host overview union mounts a rule-carried tag once, not once per route', () => {
+    // The reproduction named in the review: add a `/*` rule to a six-route
+    // host and the derived overview resolves that placement six times.
+    const topology = topologyOf(
+      [
+        route('/price', []),
+        route('/fleet', []),
+        route('/contact', []),
+        route('/chat', []),
+        route('/functional-spec', []),
+        route('/pages', []),
+      ],
+      [
+        patternRule('r1', '/*', [
+          { tag: 'price-ticker', slotId: 'price-slot' },
+        ]),
+      ],
+    )
+    const resolved = overviewUnion(topology)
+
+    expect(resolved.length).toBe(6)
+    expect(pendingMounts(resolved, new Set()).map(item => item.tag)).toEqual([
+      'price-ticker',
+    ])
+  })
+
+  test('a tag placed on two component routes mounts once on the overview — no rules involved', () => {
+    // Live today without any rules: the union is over routes, so one tag on
+    // two of them is in it twice.
+    const topology = topologyOf([
+      route('/price', [{ tag: 'price-ticker', slotId: 'price-slot' }]),
+      route('/all', [{ tag: 'price-ticker', slotId: 'price-slot' }]),
+    ])
+    const resolved = overviewUnion(topology)
+
+    expect(resolved.length).toBe(2)
+    expect(pendingMounts(resolved, new Set()).length).toBe(1)
+  })
+
+  test('keeps the FIRST resolved placement for a tag — the order the shells append in', () => {
+    const topology = topologyOf(
+      [route('/apps', [{ tag: 'workbench-brief', slotId: 'route-slot' }])],
+      [
+        patternRule('r1', '/*', [
+          { tag: 'workbench-brief', slotId: 'rule-slot' },
+        ]),
+      ],
+    )
+    // Layers are broadest-first, so the rule's placement is first — and it is
+    // the one whose `values` and slot the mount uses.
+    expect(
+      pendingMounts(resolvePlacements(topology, '/apps', 'dev'), new Set()).map(
+        item => item.slotId,
+      ),
+    ).toEqual(['rule-slot'])
+  })
+
+  test('skips a tag already latched by an earlier activation', () => {
+    const topology = topologyOf([
+      route('/price', [
+        { tag: 'price-ticker', slotId: 'price-slot' },
+        { tag: 'fleet-health', slotId: 'fleet-slot' },
+      ]),
+    ])
+    const resolved = resolvePlacements(topology, '/price', 'dev')
+
+    expect(
+      pendingMounts(resolved, new Set(['price-ticker'])).map(item => item.tag),
+    ).toEqual(['fleet-health'])
+  })
+
+  test('drops a fully overridden placement but keeps a partially overridden one', () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          { id: 'winner', tag: 'promo-banner', slotId: 'hero-slot' },
+          {
+            id: 'partial-winner',
+            tag: 'nav-crumbs',
+            slotId: 'top-bar',
+            condition: { locale: 'fr' },
+          },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          { id: 'loser', tag: 'promo-banner', slotId: 'hero-slot' },
+          { id: 'partial-loser', tag: 'nav-crumbs', slotId: 'top-bar' },
+        ]),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+
+    // `loser` renders for nobody, so it is not pending. `partial-loser` still
+    // renders for everyone outside `fr`, so it is — and it is the FIRST
+    // nav-crumbs entry, so it is the one that mounts.
+    expect(pendingMounts(resolved, new Set()).map(item => item.id)).toEqual([
+      'partial-loser',
+      'winner',
+    ])
+  })
+})
+
+// The failure mode this function exists for, verbatim from the D1 extraction:
+// an empty override merged FIRST and filtered later deletes the placement's
+// value instead of leaving it standing. `createMicroDotFromEntry`'s own
+// drop-empty filter runs over the already-merged record and cannot tell an
+// intentional `''` from "I looked and found nothing".
+describe('mountOverridesFor', () => {
+  test('a resume override wins over the placement value', () => {
+    expect(
+      mountOverridesFor({ symbol: 'FOLD' }, { symbol: 'RESUMED' }),
+    ).toEqual({ symbol: 'RESUMED' })
+  })
+
+  test('an EMPTY resume override is dropped, leaving the placement value standing', () => {
+    expect(mountOverridesFor({ symbol: 'FOLD' }, { symbol: '' })).toEqual({
+      symbol: 'FOLD',
+    })
+  })
+
+  test('an empty placement value is kept — the drop-empty rule is about OVERRIDES only', () => {
+    expect(mountOverridesFor({ symbol: '' }, {})).toEqual({ symbol: '' })
+  })
+
+  test('a resume key the placement does not have is added', () => {
+    expect(
+      mountOverridesFor({ 'component-id': 'demo' }, { 'interview-id': 'iv-1' }),
+    ).toEqual({ 'component-id': 'demo', 'interview-id': 'iv-1' })
+  })
+})

package/src/mounting.ts

@@ -0,0 +1,90 @@
+import { Array } from 'effect'
+
+import type { ResolvedPlacement } from './rules.ts'
+
+/**
+ * What a shell does with a resolution's output on the way to the DOM — the
+ * two steps between `resolvePlacements` and `createMicroDotFromEntry`.
+ *
+ * Both live here rather than in either shell because both shells need both and
+ * **apps must not import each other**; `apps/host/src/mounting.ts` held
+ * `mountOverridesFor` alone until the 2026-08-18 review found the platform
+ * re-implementing its merge inline, incorrectly (finding 5). Neither function
+ * touches the DOM, so both are testable — which is the whole point: an
+ * `entry.ts` runs `start()` at module scope and nothing in it can be tested.
+ */
+
+/**
+ * The placements this shell must still mount, given the tags it already has.
+ *
+ * **Deduped by tag as the list is built, not after** — that ordering is the
+ * defect this function exists to make impossible (2026-08-18 review, finding
+ * 1). Both shells wrote
+ *
+ * ```ts
+ * const pending = Array.filter(resolved, p => !mountedTags.has(p.tag))
+ * pending.forEach(p => mountedTags.add(p.tag))
+ * ```
+ *
+ * and `filter` runs the WHOLE predicate pass before `forEach` latches
+ * anything, so one tag resolved twice survived twice and was appended to its
+ * slot twice. It resolves twice for two live reasons: the demo host's derived
+ * overview route resolves as the union of every component route (so a `/*`
+ * rule placement is in that union once per route), and a single tag
+ * legitimately placed on two component routes is in it twice with no rules at
+ * all.
+ *
+ * A tag is loaded once and mounted once — `loadMicroDot` dedupes the fetch and
+ * a slot holds one instance — so the FIRST resolved placement for a tag wins,
+ * matching the order the shells append in.
+ *
+ * Fully overridden placements are dropped first: they render for nobody.
+ */
+export const pendingMounts = (
+  resolved: ReadonlyArray<ResolvedPlacement>,
+  mountedTags: ReadonlySet<string>,
+): ReadonlyArray<ResolvedPlacement> =>
+  Array.dedupeWith(
+    Array.filter(
+      resolved,
+      placement =>
+        placement.state !== 'overridden' && !mountedTags.has(placement.tag),
+    ),
+    (a, b) => a.tag === b.tag,
+  )
+
+/**
+ * The mount-time merge, after Phase 5's values migration (work item 2 of
+ * `wiki/plans/shipped/microdots-platform-phase-5-pages-design.md`):
+ * attribute data moved out of the registry into the topology placements'
+ * `values`, so what reaches `createMicroDotFromEntry`'s `overrides` is
+ *
+ *   placement.values → resume overrides (the browser's memory), which win.
+ *
+ * The registry's `attributes` still spread FIRST inside
+ * `createMicroDotFromEntry` — the API stays for foreign hosts — but this
+ * repo's registry data is empty since the migration.
+ *
+ * Resume entries are dropped when EMPTY here, BEFORE the merge: "I looked and
+ * found nothing" must leave the placement's value standing, and an empty
+ * override merged first and filtered later would delete it instead. That is
+ * the exact lesson `createMicroDotFromEntry` learned in the D1 extraction
+ * (`loader.ts`), replayed one layer up now that placement values travel
+ * through its `overrides` parameter — its own drop-empty filter runs over the
+ * ALREADY-merged record and cannot make this distinction.
+ *
+ * **Call this even when the resume source provably never returns `''`.** The
+ * platform spread the two records inline on exactly that reasoning and was
+ * therefore one new resume source away from silently deleting a placement
+ * value — a correctness argument that has to be re-proved by every future
+ * reader is not a safeguard.
+ */
+export const mountOverridesFor = (
+  values: Readonly<Record<string, string>>,
+  resume: Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> => ({
+  ...values,
+  ...Object.fromEntries(
+    Object.entries(resume).filter(([, value]) => value !== ''),
+  ),
+})