@bespokeagentics/microdots-host 0.1.0 → 0.1.1

package/src/slotDom.test.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, test } from 'vitest'
+
+import {
+  ensureSection,
+  ensureSlot,
+  pruneGeneratedContainers,
+} from './slotDom.ts'
+
+/**
+ * Containers for placements the build never knew about.
+ *
+ * Two properties carry this module, and both fail silently when broken:
+ *
+ * 1. **A generated slot carries its id.** Foldkit dies without one and
+ *    `Runtime.embed` swallows the defect, so the dot renders nothing on a clean
+ *    console with a green suite.
+ * 2. **Existing markup is never regenerated over.** The demo host's sections
+ *    carry a heading and a description that exist nowhere in the topology;
+ *    replacing them would quietly turn a showcase into bare boxes, and no
+ *    assertion about mounting would notice.
+ */
+
+const SECTION_CLASS = 'generated-section'
+const SLOT_CLASS = 'generated-slot'
+
+const generatedRoot = (): HTMLElement => {
+  const root = document.createElement('div')
+  root.id = 'generated-sections'
+  document.body.appendChild(root)
+  return root
+}
+
+/** A hand-written section, copy and all — what must never be overwritten. */
+const writtenSection = (sectionId: string, slotId: string): HTMLElement => {
+  const section = document.createElement('section')
+  section.id = sectionId
+  section.innerHTML = `<div><h2>Readout view</h2><p>Public readout surface.</p></div><div id="${slotId}"></div>`
+  document.body.appendChild(section)
+  return section
+}
+
+beforeEach(() => {
+  document.body.replaceChildren()
+})
+
+describe('ensureSection', () => {
+  test('creates a section carrying its declared id', () => {
+    const root = generatedRoot()
+
+    const section = ensureSection('section-new', root, SECTION_CLASS)
+
+    expect(section.id).toBe('section-new')
+    expect(section.tagName).toBe('SECTION')
+    expect(section.parentElement).toBe(root)
+    expect(section.dataset['generated']).toBe('true')
+  })
+
+  test('the id is what lets `activate` hide it — without it the dot renders on every route', () => {
+    const root = generatedRoot()
+    ensureSection('section-new', root, SECTION_CLASS)
+
+    expect(document.getElementById('section-new')).not.toBeNull()
+  })
+
+  test('returns hand-written markup UNTOUCHED — the copy survives', () => {
+    const root = generatedRoot()
+    const written = writtenSection('section-readout-view', 'readout-view-slot')
+
+    const found = ensureSection('section-readout-view', root, SECTION_CLASS)
+
+    expect(found).toBe(written)
+    expect(found.querySelector('h2')?.textContent).toBe('Readout view')
+    expect(found.dataset['generated']).toBeUndefined()
+    expect(root.childElementCount).toBe(0)
+  })
+
+  test('is idempotent — a second call adds nothing', () => {
+    const root = generatedRoot()
+
+    const first = ensureSection('section-new', root, SECTION_CLASS)
+    const second = ensureSection('section-new', root, SECTION_CLASS)
+
+    expect(second).toBe(first)
+    expect(root.childElementCount).toBe(1)
+  })
+})
+
+describe('ensureSlot', () => {
+  test('THE INVARIANT: a created slot carries its id', () => {
+    const root = generatedRoot()
+    const section = ensureSection('section-new', root, SECTION_CLASS)
+
+    const slot = ensureSlot('new-slot', section, SLOT_CLASS)
+
+    // Foldkit dies without this, and `Runtime.embed` forks the runtime so the
+    // defect never reaches the console.
+    expect(slot.id).toBe('new-slot')
+    expect(document.getElementById('new-slot')).toBe(slot)
+    expect(slot.parentElement).toBe(section)
+  })
+
+  test('returns a hand-written slot untouched, and does not move it', () => {
+    const root = generatedRoot()
+    const written = writtenSection('section-readout-view', 'readout-view-slot')
+    const section = ensureSection('section-readout-view', root, SECTION_CLASS)
+
+    const slot = ensureSlot('readout-view-slot', section, SLOT_CLASS)
+
+    expect(slot).toBe(written.querySelector('#readout-view-slot'))
+    expect(slot.dataset['generated']).toBeUndefined()
+  })
+
+  test('is idempotent — a second call does not add a second slot', () => {
+    const root = generatedRoot()
+    const section = ensureSection('section-new', root, SECTION_CLASS)
+
+    const first = ensureSlot('new-slot', section, SLOT_CLASS)
+    const second = ensureSlot('new-slot', section, SLOT_CLASS)
+
+    expect(second).toBe(first)
+    expect(section.childElementCount).toBe(1)
+  })
+})
+
+describe('pruneGeneratedContainers', () => {
+  test('removes a generated slot and its section once the dot is unmounted', () => {
+    const root = generatedRoot()
+    const section = ensureSection('section-new', root, SECTION_CLASS)
+    const slot = ensureSlot('new-slot', section, SLOT_CLASS)
+    slot.appendChild(document.createElement('new-dot'))
+
+    // Still mounted: nothing is pruned.
+    expect(pruneGeneratedContainers(root)).toBe(0)
+
+    // The unmount removed the MicroDot's element, leaving the scaffolding.
+    slot.replaceChildren()
+
+    expect(pruneGeneratedContainers(root)).toBe(2)
+    expect(document.getElementById('new-slot')).toBeNull()
+    expect(document.getElementById('section-new')).toBeNull()
+  })
+
+  test('never touches hand-written markup, however empty', () => {
+    const root = generatedRoot()
+    const written = writtenSection('section-readout-view', 'readout-view-slot')
+
+    expect(pruneGeneratedContainers(root)).toBe(0)
+    expect(written.isConnected).toBe(true)
+    expect(document.getElementById('readout-view-slot')).not.toBeNull()
+  })
+})

package/src/slotDom.ts

@@ -0,0 +1,111 @@
+/**
+ * Containers for placements the BUILD never knew about.
+ *
+ * Until Phase B of `wiki/plans/active/wiring-live-placement-on-a-remote-host.md`
+ * a shell could only mount a MicroDot into a `<div id="…-slot">` somebody had
+ * hand-written into `index.html`. That is fine while the topology is compiled
+ * in and cannot change; it is fatal the moment the topology is fetched, because
+ * a placement added at runtime has nowhere to go and `getElementById` returns
+ * `null`.
+ *
+ * **Markup wins; this is the fallback.** The demo host's twenty-five sections
+ * carry a heading and a description per dot that exist nowhere in the topology
+ * — the slot manifest declares `id`, `kind`, `row`, `width` and `capacity`, and
+ * no copy. Generating over the top of them would silently delete that copy and
+ * turn a showcase into a stack of bare boxes, so an element that already exists
+ * is always returned as-is. See
+ * `wiki/framework/composition/gap-a-generated-section-has-no-copy-to-render.md`.
+ *
+ * Neither function reads a topology or a route: they take ids and a container,
+ * so they are testable without a shell, which is the same reason
+ * `mounting.ts` exists.
+ */
+
+/**
+ * The `<section>` a route reveals, created in `generatedRoot` if the page has
+ * none.
+ *
+ * The id matters as much as it does for a slot, though for a different reason:
+ * `activate` hides and shows sections by the ids in `route.sectionIds`, so a
+ * generated section that does not carry its declared id is a section that never
+ * hides — its MicroDot would then render on every route.
+ */
+export const ensureSection = (
+  sectionId: string,
+  generatedRoot: HTMLElement,
+  className: string,
+): HTMLElement => {
+  const existing = document.getElementById(sectionId)
+  if (existing !== null) return existing
+
+  const section = document.createElement('section')
+  section.id = sectionId
+  section.className = className
+  section.dataset['generated'] = 'true'
+  generatedRoot.appendChild(section)
+  return section
+}
+
+/**
+ * The `<div>` a MicroDot mounts into, created inside `section` if the page has
+ * none.
+ *
+ * **The `id` assignment on the created element is load-bearing and is the
+ * single most expensive failure in this repo.** Foldkit dies if its mount
+ * container has no `id`, and `Runtime.embed` forks the runtime, so the startup
+ * defect never reaches the console: the MicroDot renders nothing, the console
+ * is clean, and typecheck, lint, tests and build are all green. Hand-written
+ * slots got their ids from a human reading `host-topology.json`; a generated
+ * one gets it from here or from nowhere. See
+ * `wiki/patterns-and-traps/mount-container-needs-an-id.md`.
+ */
+export const ensureSlot = (
+  slotId: string,
+  section: HTMLElement,
+  className: string,
+): HTMLElement => {
+  const existing = document.getElementById(slotId)
+  if (existing !== null) return existing
+
+  const slot = document.createElement('div')
+  // Never omit, never rename, never defer to a caller: see above.
+  slot.id = slotId
+  slot.className = className
+  slot.dataset['generated'] = 'true'
+  section.appendChild(slot)
+  return slot
+}
+
+/**
+ * Remove generated sections that are now empty.
+ *
+ * An unmount removes the MicroDot's element but leaves the container that was
+ * generated for it, and a page that accumulates empty boxes every time a dot is
+ * removed looks broken in a way no assertion catches. Hand-written sections are
+ * never touched — they are the page, not scaffolding — which is what
+ * `data-generated` distinguishes.
+ */
+export const pruneGeneratedContainers = (
+  generatedRoot: HTMLElement,
+): number => {
+  const sections = Array.from(
+    generatedRoot.querySelectorAll('section[data-generated="true"]'),
+  )
+  let removed = 0
+  sections.forEach(section => {
+    const slots = Array.from(
+      section.querySelectorAll('div[data-generated="true"]'),
+    )
+    slots.forEach(slot => {
+      if (slot.childElementCount === 0) {
+        slot.remove()
+        removed += 1
+      }
+    })
+    if (section.childElementCount === 0) {
+      section.remove()
+      removed += 1
+    }
+  })
+  return removed
+}

package/src/slotResize.test.ts

@@ -0,0 +1,392 @@
+import { beforeEach, describe, expect, test } from 'vitest'
+
+import {
+  SLOT_RESIZE_HANDLE_CLASS,
+  type SlotResizeStorage,
+  applySlotSize,
+  attachSlotResize,
+  chromeOfSlot,
+  clearSlotResize,
+  restoreSlotResize,
+  slotResizeStorageKey,
+  slotSizeVar,
+} from './slotResize.ts'
+import type { SlotSpec } from './slots.ts'
+
+const slot = (id: string, resize: SlotSpec['resize']): SlotSpec =>
+  resize === undefined
+    ? { id, kind: 'rail', row: 1 }
+    : { id, kind: 'rail', row: 1, resize }
+
+const memoryStorage = (): SlotResizeStorage => {
+  const values = new Map<string, string>()
+  return {
+    getItem: key => values.get(key) ?? null,
+    removeItem: key => {
+      values.delete(key)
+    },
+    setItem: (key, value) => {
+      values.set(key, value)
+    },
+  }
+}
+
+const wiringShell = (): {
+  readonly section: HTMLElement
+  readonly drawer: HTMLElement
+  readonly bottom: HTMLElement
+} => {
+  const section = document.createElement('section')
+  section.id = 'section-wiring'
+  const canvas = document.createElement('div')
+  canvas.id = 'wiring-canvas-slot'
+  const drawer = document.createElement('div')
+  drawer.className = 'wiring-drawer'
+  Object.defineProperty(drawer, 'offsetWidth', {
+    value: 380,
+    configurable: true,
+  })
+  Object.defineProperty(drawer, 'offsetHeight', {
+    value: 600,
+    configurable: true,
+  })
+  const inspector = document.createElement('div')
+  inspector.id = 'wiring-inspector-slot'
+  const trace = document.createElement('div')
+  trace.id = 'wiring-trace-slot'
+  drawer.append(inspector, trace)
+  const bottom = document.createElement('div')
+  bottom.className = 'wiring-bottom'
+  Object.defineProperty(bottom, 'offsetWidth', {
+    value: 800,
+    configurable: true,
+  })
+  Object.defineProperty(bottom, 'offsetHeight', {
+    value: 200,
+    configurable: true,
+  })
+  const table = document.createElement('div')
+  table.id = 'wiring-table-slot'
+  bottom.append(table)
+  section.append(canvas, drawer, bottom)
+  Object.defineProperty(section, 'clientHeight', {
+    value: 800,
+    configurable: true,
+  })
+  document.body.append(section)
+  return { section, drawer, bottom }
+}
+
+beforeEach(() => {
+  document.body.replaceChildren()
+  window.sessionStorage.clear()
+})
+
+describe('chromeOfSlot', () => {
+  test('a nested tab pane resizes its grid-area ancestor, not the hidden tab', () => {
+    const { section, drawer } = wiringShell()
+    const inspector = document.getElementById('wiring-inspector-slot')
+    expect(inspector).not.toBeNull()
+    if (inspector === null) return
+    expect(chromeOfSlot(inspector, section)).toBe(drawer)
+  })
+})
+
+describe('attachSlotResize', () => {
+  test('slots without resize get no handle', () => {
+    const { section } = wiringShell()
+    attachSlotResize({
+      section,
+      slots: [slot('wiring-canvas-slot', undefined)],
+    })
+    expect(section.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)).toBeNull()
+  })
+
+  test('a missing slot id is skipped — generated later, not a throw', () => {
+    const { section } = wiringShell()
+    expect(() =>
+      attachSlotResize({
+        section,
+        slots: [slot('wiring-missing-slot', 'x')],
+      }),
+    ).not.toThrow()
+    expect(section.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)).toBeNull()
+  })
+
+  test('inspector + trace share the drawer — one x handle, not two', () => {
+    const { section, drawer } = wiringShell()
+    attachSlotResize({
+      section,
+      slots: [
+        slot('wiring-inspector-slot', 'x'),
+        slot('wiring-trace-slot', 'x'),
+      ],
+    })
+    expect(drawer.querySelectorAll(`.${SLOT_RESIZE_HANDLE_CLASS}`).length).toBe(
+      1,
+    )
+  })
+
+  test('x and y handles land on their chrome, titled from the prototype', () => {
+    const { section, drawer, bottom } = wiringShell()
+    attachSlotResize({
+      section,
+      slots: [
+        slot('wiring-inspector-slot', 'x'),
+        slot('wiring-table-slot', 'y'),
+      ],
+    })
+    const x = drawer.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)
+    const y = bottom.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)
+    expect(x).toBeInstanceOf(HTMLButtonElement)
+    expect(y).toBeInstanceOf(HTMLButtonElement)
+    if (
+      !(x instanceof HTMLButtonElement) ||
+      !(y instanceof HTMLButtonElement)
+    ) {
+      return
+    }
+    expect(x.dataset['axis']).toBe('x')
+    expect(y.dataset['axis']).toBe('y')
+    expect(x.title).toBe('Drag to resize')
+    expect(y.title).toBe('Drag to resize')
+  })
+
+  test('dragging the drawer left grows it and marks data-resized', () => {
+    const { section, drawer } = wiringShell()
+    attachSlotResize({
+      section,
+      slots: [slot('wiring-inspector-slot', 'x')],
+    })
+    const handle = drawer.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)
+    expect(handle).toBeInstanceOf(HTMLButtonElement)
+    if (!(handle instanceof HTMLButtonElement)) return
+
+    handle.dispatchEvent(
+      new PointerEvent('pointerdown', {
+        bubbles: true,
+        clientX: 900,
+        clientY: 100,
+        button: 0,
+        pointerId: 1,
+      }),
+    )
+    document.dispatchEvent(
+      new PointerEvent('pointermove', {
+        bubbles: true,
+        clientX: 820,
+        clientY: 100,
+        pointerId: 1,
+      }),
+    )
+    document.dispatchEvent(
+      new PointerEvent('pointerup', {
+        bubbles: true,
+        clientX: 820,
+        clientY: 100,
+        pointerId: 1,
+      }),
+    )
+
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-inspector-slot')),
+    ).toBe('460px')
+    expect(section.dataset['resized']).toBe('x')
+  })
+
+  test('ArrowLeft on the drawer handle grows it', () => {
+    const { section, drawer } = wiringShell()
+    attachSlotResize({
+      section,
+      slots: [slot('wiring-inspector-slot', 'x')],
+    })
+    const handle = drawer.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)
+    expect(handle).toBeInstanceOf(HTMLButtonElement)
+    if (!(handle instanceof HTMLButtonElement)) return
+    handle.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }),
+    )
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-inspector-slot')),
+    ).toBe('388px')
+  })
+
+  test('detach removes the handles', () => {
+    const { section, drawer } = wiringShell()
+    const attached = attachSlotResize({
+      section,
+      slots: [slot('wiring-inspector-slot', 'x')],
+    })
+    attached.detach()
+    expect(drawer.querySelector(`.${SLOT_RESIZE_HANDLE_CLASS}`)).toBeNull()
+  })
+})
+
+describe('clearSlotResize', () => {
+  test('drops the CSS vars and data-resized so a named preset can apply', () => {
+    const { section } = wiringShell()
+    applySlotSize(section, 'wiring-inspector-slot', 'x', 500)
+    applySlotSize(section, 'wiring-table-slot', 'y', 240)
+    expect(section.dataset['resized']).toBe('x y')
+    clearSlotResize(section, [
+      slot('wiring-inspector-slot', 'x'),
+      slot('wiring-table-slot', 'y'),
+    ])
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-inspector-slot')),
+    ).toBe('')
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-table-slot')),
+    ).toBe('')
+    expect(section.dataset['resized']).toBeUndefined()
+  })
+})
+
+describe('applySlotSize', () => {
+  test('clamps the drawer to the prototype 300–980 band', () => {
+    const { section } = wiringShell()
+    expect(applySlotSize(section, 'wiring-inspector-slot', 'x', 12)).toBe(300)
+    expect(applySlotSize(section, 'wiring-inspector-slot', 'x', 2000)).toBe(980)
+  })
+})
+
+describe('tab-session persistence', () => {
+  test('stores slot id, axis, and the clamped pixel size', () => {
+    const storage = memoryStorage()
+    const { section } = wiringShell()
+    applySlotSize(section, 'wiring-inspector-slot', 'x', 2_000, storage)
+    expect(storage.getItem(slotResizeStorageKey(section.id))).toBe(
+      '{"version":1,"sizes":[{"slotId":"wiring-inspector-slot","axis":"x","px":980}]}',
+    )
+  })
+
+  test('a fresh section restores both axes before handles attach', () => {
+    const storage = memoryStorage()
+    const first = wiringShell()
+    applySlotSize(first.section, 'wiring-inspector-slot', 'x', 480, storage)
+    applySlotSize(first.section, 'wiring-table-slot', 'y', 252, storage)
+
+    document.body.replaceChildren()
+    const fresh = wiringShell()
+    attachSlotResize({
+      section: fresh.section,
+      slots: [
+        slot('wiring-inspector-slot', 'x'),
+        slot('wiring-table-slot', 'y'),
+      ],
+      storage,
+    })
+
+    expect(
+      fresh.section.style.getPropertyValue(
+        slotSizeVar('wiring-inspector-slot'),
+      ),
+    ).toBe('480px')
+    expect(
+      fresh.section.style.getPropertyValue(slotSizeVar('wiring-table-slot')),
+    ).toBe('252px')
+    expect(fresh.section.dataset['resized']).toBe('x y')
+  })
+
+  test('a hidden route restores its vertical size without clamping it to 46px', () => {
+    const storage = memoryStorage()
+    const first = wiringShell()
+    applySlotSize(first.section, 'wiring-table-slot', 'y', 252, storage)
+
+    document.body.replaceChildren()
+    const fresh = wiringShell()
+    fresh.section.hidden = true
+    Object.defineProperty(fresh.section, 'clientHeight', {
+      value: 0,
+      configurable: true,
+    })
+    attachSlotResize({
+      section: fresh.section,
+      slots: [slot('wiring-table-slot', 'y')],
+      storage,
+    })
+
+    expect(
+      fresh.section.style.getPropertyValue(slotSizeVar('wiring-table-slot')),
+    ).toBe('252px')
+    expect(storage.getItem(slotResizeStorageKey(fresh.section.id))).toBe(
+      '{"version":1,"sizes":[{"slotId":"wiring-table-slot","axis":"y","px":252}]}',
+    )
+  })
+
+  test('a named preset clears storage as well as the live DOM override', () => {
+    const storage = memoryStorage()
+    const first = wiringShell()
+    const slots = [
+      slot('wiring-inspector-slot', 'x'),
+      slot('wiring-table-slot', 'y'),
+    ]
+    applySlotSize(first.section, 'wiring-inspector-slot', 'x', 480, storage)
+    applySlotSize(first.section, 'wiring-table-slot', 'y', 252, storage)
+    clearSlotResize(first.section, slots, storage)
+    expect(storage.getItem(slotResizeStorageKey(first.section.id))).toBeNull()
+
+    document.body.replaceChildren()
+    const fresh = wiringShell()
+    attachSlotResize({ section: fresh.section, slots, storage })
+    expect(
+      fresh.section.style.getPropertyValue(
+        slotSizeVar('wiring-inspector-slot'),
+      ),
+    ).toBe('')
+    expect(fresh.section.dataset['resized']).toBeUndefined()
+  })
+
+  test('missing and malformed storage restore no override', () => {
+    const malformed = memoryStorage()
+    const first = wiringShell()
+    malformed.setItem(slotResizeStorageKey(first.section.id), '{not json')
+    expect(() =>
+      restoreSlotResize(
+        first.section,
+        [slot('wiring-inspector-slot', 'x')],
+        malformed,
+      ),
+    ).not.toThrow()
+    expect(
+      first.section.style.getPropertyValue(
+        slotSizeVar('wiring-inspector-slot'),
+      ),
+    ).toBe('')
+
+    expect(() =>
+      restoreSlotResize(
+        first.section,
+        [slot('wiring-inspector-slot', 'x')],
+        null,
+      ),
+    ).not.toThrow()
+  })
+
+  test('throwing storage never blocks live resize or preset clear', () => {
+    const throwing: SlotResizeStorage = {
+      getItem: () => {
+        throw new Error('denied')
+      },
+      removeItem: () => {
+        throw new Error('denied')
+      },
+      setItem: () => {
+        throw new Error('denied')
+      },
+    }
+    const { section } = wiringShell()
+    const slots = [slot('wiring-inspector-slot', 'x')]
+
+    expect(() =>
+      applySlotSize(section, 'wiring-inspector-slot', 'x', 500, throwing),
+    ).not.toThrow()
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-inspector-slot')),
+    ).toBe('500px')
+    expect(() => clearSlotResize(section, slots, throwing)).not.toThrow()
+    expect(
+      section.style.getPropertyValue(slotSizeVar('wiring-inspector-slot')),
+    ).toBe('')
+  })
+})