@tapcue/extension-sdk 0.1.0

package/src/view-runtime.ts

@@ -0,0 +1,270 @@
+/**
+ * The isolate-side reactive loop (docs/architecture/extension-ui-interactive.md §4, §8).
+ *
+ * `renderView` runs a `view` handler once to produce the initial `{view, model, actions}`.
+ * `applyAction` re-runs the handler to rebuild the signal graph, hydrates it from the model the
+ * shell handed back, dispatches one action, and returns the model cells that changed as a patch.
+ * The handler is a pure function of its request and context; all interactivity is signals it
+ * created plus actions it declared, which is why a cold isolate can rehydrate and act (§3).
+ *
+ * bootstrap.js calls these from `__tapcue.scopeView` / `__tapcue.scopeViewAction`; the fake test
+ * host calls them directly so an extension's view can be unit-tested with no host at all.
+ */
+
+import { ExtensionError } from "./errors.js";
+import type { JsonValue } from "./json.js";
+import { BuildContext, registerLiveBuild, runInBuild } from "./reactive.js";
+import type { VisibleCleanup } from "./reactive.js";
+import type { ActionContext, ExtensionContext } from "./types.js";
+import type { ActionDescriptor, ActionPatch, DataModel, PatchOp, ViewNode, ViewResult } from "./view.js";
+
+/**
+ * A view handler: a pure builder of a bound tree. Signals/actions register as it runs. It may be
+ * async — awaiting the initial data it binds (a forecast, a search) before describing itself — as
+ * long as signal/action creation order is deterministic across runs (an action dispatch re-runs it
+ * to rebuild the graph before hydrating from the model).
+ */
+export type ViewHandler<Request> = (
+  request: Request,
+  ctx: ExtensionContext,
+) => ViewNode | Promise<ViewNode>;
+
+function describeActions(build: BuildContext): ActionDescriptor[] {
+  return [...build.actions.values()].map((action) => {
+    const descriptor: ActionDescriptor = { id: action.id };
+    if (action.requires !== undefined) descriptor.requires = action.requires;
+    if (action.destructive !== undefined) descriptor.destructive = action.destructive;
+    return descriptor;
+  });
+}
+
+function modelOf(build: BuildContext): DataModel {
+  const model: DataModel = {};
+  for (const path of build.order) {
+    model[path] = build.values.get(path) as JsonValue;
+  }
+  return model;
+}
+
+export async function renderView<Request>(
+  view: ViewHandler<Request>,
+  request: Request,
+  ctx: ExtensionContext,
+): Promise<ViewResult> {
+  const build = new BuildContext();
+  const root = await runInBuild(build, () => view(request, ctx));
+  return { kind: "view", view: root, model: modelOf(build), actions: describeActions(build) };
+}
+
+function encode(value: JsonValue | undefined): string {
+  return JSON.stringify(value ?? null);
+}
+
+/**
+ * The cells that moved since `previous`, as patch ops, advancing `previous` as it goes.
+ *
+ * What a patch *is* — walk the build order, compare against the last snapshot, emit the changed
+ * cells — is the shape the shell's `ExtensionViewStore.apply` must mirror, so it is stated here
+ * rather than inline. The snapshot holds each cell already serialized, so an unchanged cell costs
+ * one encode and a string compare rather than re-encoding both sides.
+ */
+function diffModel(build: BuildContext, previous: Map<string, string>): PatchOp[] {
+  const ops: PatchOp[] = [];
+  for (const path of build.order) {
+    diffCell(path, build.values.get(path) as JsonValue, previous, ops);
+  }
+  return ops;
+}
+
+/**
+ * Emit the ops that turn a cell's previous value into `next`, and advance `previous`.
+ *
+ * An array cell is diffed **element by element** rather than replaced whole: a `<Table>`'s rows are
+ * one array signal, so without this a single row's number moving re-sends every row every tick. The
+ * extension builds the array in a stable order (a process list is pid-ordered), so element `i` is
+ * the same row across ticks and only the few that actually moved travel, as `s0[i]`. A cell that is
+ * not an array is set whole, as before.
+ */
+function diffCell(path: string, next: JsonValue, previous: Map<string, string>, ops: PatchOp[]): void {
+  if (Array.isArray(next)) {
+    const prevLen = Number(previous.get(`${path}#len`) ?? "-1");
+    for (let i = 0; i < next.length; i++) {
+      const key = `${path}[${i}]`;
+      const encoded = encode(next[i]);
+      if (previous.get(key) !== encoded) {
+        ops.push({ op: "set", path: key, value: next[i] });
+        previous.set(key, encoded);
+      }
+    }
+    // The array shrank: drop the tail, highest index first so a truncating apply stays in step.
+    for (let i = next.length; i < prevLen; i++) {
+      ops.push({ op: "remove", path: `${path}[${i}]` });
+      previous.delete(`${path}[${i}]`);
+    }
+    // A cell that used to be a scalar (prevLen === -1) needs its old whole value cleared, or a
+    // reader could keep it beside the new elements.
+    if (prevLen === -1 && previous.has(path)) {
+      previous.delete(path);
+    }
+    previous.set(`${path}#len`, String(next.length));
+    return;
+  }
+
+  const encoded = encode(next);
+  if (previous.get(path) !== encoded) {
+    ops.push({ op: "set", path, value: next });
+    previous.set(path, encoded);
+  }
+  previous.delete(`${path}#len`);
+}
+
+/** Every cell of `build`, serialized to the same keys `diffCell` compares against. */
+function snapshot(build: BuildContext): Map<string, string> {
+  const baseline = new Map<string, string>();
+  for (const [path, value] of build.values) {
+    if (Array.isArray(value)) {
+      value.forEach((element, i) => baseline.set(`${path}[${i}]`, encode(element as JsonValue)));
+      baseline.set(`${path}#len`, String(value.length));
+    } else {
+      baseline.set(path, encode(value as JsonValue));
+    }
+  }
+  return baseline;
+}
+
+/**
+ * Where a kept-alive view's patches go, and when it should stop.
+ *
+ * The runtime supplies `signal` from the view's run window — aborted when the surface stops being
+ * shown — and turns each flush into a streamed patch frame.
+ */
+export interface ViewDriver {
+  /** Each flushed patch, in order: one per microtask batch of signal writes. */
+  onPatch(patch: PatchOp[]): void;
+  /** Aborts when the view stops being visible. */
+  signal: AbortSignal;
+  /** Called once the initial frame is out and the setups have started. */
+  onReady?(): void;
+}
+
+/**
+ * Render a view, then keep it alive for as long as its `whileVisible` setups have work.
+ *
+ * The initial frame is emitted before any setup runs, so a write on a setup's very first tick can
+ * never arrive before the frame it patches. After that the render is signal-driven: `build.onDirty`
+ * is wired, so any `signal.set()` a setup makes schedules one microtask flush that diffs the model
+ * and streams the cells that moved. Nothing is explicitly pushed.
+ *
+ * A view with no setups emits and returns — that is every ordinary pane, and it costs what it
+ * always did. There is no flag distinguishing the two; what happens follows from what the view
+ * left running.
+ */
+export async function driveView<Request>(
+  view: ViewHandler<Request>,
+  request: Request,
+  ctx: ExtensionContext,
+  emit: (result: ViewResult) => void,
+  driver: ViewDriver,
+): Promise<void> {
+  const build = new BuildContext();
+  const root = await runInBuild(build, () => view(request, ctx));
+  const result: ViewResult = {
+    kind: "view",
+    view: root,
+    model: modelOf(build),
+    actions: describeActions(build),
+  };
+
+  if (build.visibleSetups.length === 0) {
+    emit(result);
+    driver.onReady?.();
+    return;
+  }
+
+  // Wired before emitting, so a set made on a setup's very first tick is never lost.
+  const last = snapshot(build);
+  let scheduled = false;
+  const flush = () => {
+    scheduled = false;
+    const ops = diffModel(build, last);
+    if (ops.length > 0) driver.onPatch(ops);
+  };
+  build.onDirty = () => {
+    if (scheduled || driver.signal.aborted) return;
+    scheduled = true;
+    queueMicrotask(flush);
+  };
+
+  // Setups are torn down and re-run as a unit, not once for the view's whole life. Two things
+  // ask for that: the visible window ending (the original reason), and a **setting the view
+  // follows changing** — a loop already armed at 5 s does not start ticking at 1 s because a
+  // value changed, it has to be re-armed. `whileVisible` has always promised idempotence, so
+  // re-running is within the contract it already signs.
+  let cleanups: VisibleCleanup[] = [];
+  const teardown = () => {
+    const previous = cleanups;
+    cleanups = [];
+    for (const cleanup of previous) {
+      if (typeof cleanup === "function") cleanup();
+    }
+  };
+  const startSetups = async () => {
+    cleanups = await Promise.all(build.visibleSetups.map((setup) => setup()));
+  };
+  const unregister = registerLiveBuild({
+    build,
+    async restartSetups() {
+      if (driver.signal.aborted) return;
+      teardown();
+      await startSetups();
+    },
+  });
+
+  emit(result);
+  await startSetups();
+  driver.onReady?.();
+
+  await new Promise<void>((resolve) => {
+    if (driver.signal.aborted) return resolve();
+    driver.signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+  unregister();
+  build.onDirty = null;
+  teardown();
+}
+
+export async function applyAction<Request>(
+  view: ViewHandler<Request>,
+  request: Request,
+  ctx: ActionContext,
+  actionId: string,
+  args: JsonValue[],
+  model: DataModel,
+): Promise<ActionPatch> {
+  const build = new BuildContext();
+  // Rebuild the signal graph and action registry deterministically, then hydrate it from the
+  // model the shell holds. Signal creation order must match the initial render for this to line
+  // up — the rules-of-hooks discipline (reactive.ts).
+  await runInBuild(build, () => view(request, ctx));
+  for (const [path, value] of Object.entries(model)) {
+    build.values.set(path, value);
+  }
+
+  const action = build.actions.get(actionId);
+  if (action === undefined) {
+    throw new ExtensionError({ code: "invalid-result", message: `unknown action: ${actionId}` });
+  }
+
+  // Registered so an action that writes a setting writes it into *this* build too — the patch
+  // below is what tells the shell about it. Its setups are never run here (an action does not
+  // present a view), so there is nothing to restart. Unregistered whatever the action does:
+  // this build lives exactly as long as the call.
+  const unregister = registerLiveBuild({ build, async restartSetups() {} });
+  const before = snapshot(build);
+  try {
+    await action.run(ctx, args);
+  } finally {
+    unregister();
+  }
+  return { kind: "patch", patch: diffModel(build, before) };
+}

package/src/view.ts

@@ -0,0 +1,116 @@
+/**
+ * The interactive view wire format. See docs/architecture/extension-ui-interactive.md.
+ *
+ * These are the JSON shapes that cross the isolate ↔ shell boundary. The authoring
+ * API (`signal`, `action`, the JSX components) is sugar that compiles to exactly
+ * these — the shell only ever sees this. Nothing here is React: a `ViewNode` tree is
+ * a snapshot of bindings into a serializable `DataModel`, not a component instance.
+ */
+
+import type { JsonValue } from "./json.js";
+import type { PermissionUnit } from "./manifest.js";
+
+/** A dotted path into the `DataModel`. `@item` / `@index` are `<For>`-scope locals. */
+export type ModelPath = string;
+
+/** A reference to a model cell the shell reads without waking the isolate. */
+export interface Bind {
+  $bind: ModelPath;
+}
+
+/** A reference to a declared action; the event supplies the args. */
+export interface ActionRef {
+  $action: string;
+}
+
+/** A reference into a bounded, shell-evaluable derivation (§4, the closed binding vocabulary). */
+export interface DeriveRef {
+  $derive: Derivation;
+}
+
+/** The closed binding vocabulary. Starts tiny; grows on evidence (§12). */
+export type Derivation =
+  | { op: "not"; of: PropValue }
+  | { op: "isEmpty"; of: PropValue }
+  | { op: "notEmpty"; of: PropValue }
+  | { op: "format"; of: PropValue; as: "number" | "percent" | "date" }
+  /**
+   * Index a table the view already produced. Pure, total (a missing key resolves to nothing),
+   * and bounded — the table is data, not a callback, and the shell only ever reads it.
+   *
+   * It exists because a pane that lets the user *change* something could previously display
+   * only facts that did not depend on what changed. `value` and `font` bind because the cell
+   * holds exactly what the widget draws; "the classification of whichever family is selected"
+   * is a lookup, and without one an extension either wakes the isolate on every keystroke or
+   * renders a value computed once and now stale. The fonts playground shipped the second kind:
+   * it read "Serif / Plain" beside a specimen set in a monospace face, and nothing errored,
+   * because a stale value looks exactly like a fresh one.
+   */
+  | { op: "lookup"; of: PropValue; in: Record<string, PropValue> };
+
+/** A prop value: a literal, or one tagged binding form. */
+export type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Bind
+  | ActionRef
+  | DeriveRef
+  | PropValue[]
+  | { [key: string]: PropValue };
+
+/**
+ * A serialized element. `type` is a member of the closed component vocabulary (§5);
+ * an unknown type is dropped by the shell, never guessed at. Props may be literals or
+ * bindings; `children` may itself hold nested nodes; `slots` carry named node props
+ * (e.g. a `<Show>` fallback) that are trees rather than values.
+ */
+export interface ViewNode {
+  type: string;
+  props?: Record<string, PropValue>;
+  slots?: Record<string, ViewNode>;
+  children?: ViewNode[];
+  key?: string;
+}
+
+/** The serializable state. Every value is JSON — that is what makes rehydration cheap (§3). */
+export type DataModel = Record<ModelPath, JsonValue>;
+
+/** A declared action, surfaced so the shell can gate on `requires` and confirm `destructive`. */
+export interface ActionDescriptor {
+  id: string;
+  requires?: PermissionUnit;
+  destructive?: boolean;
+}
+
+/** What a `view` handler produces on first render. */
+export interface ViewResult {
+  kind: "view";
+  view: ViewNode;
+  model: DataModel;
+  actions: ActionDescriptor[];
+}
+
+/** One model mutation. `set` is the only op v1 emits; `remove` reserved for structural change. */
+export type PatchOp =
+  | { op: "set"; path: ModelPath; value: JsonValue }
+  | { op: "remove"; path: ModelPath };
+
+/** What an action produces: model patches, and — only if structure changed — a fresh tree. */
+export interface ActionPatch {
+  kind: "patch";
+  patch: PatchOp[];
+  view?: ViewNode;
+}
+
+/** Type guards the shell-side and test host share. */
+export function isBind(value: unknown): value is Bind {
+  return typeof value === "object" && value !== null && "$bind" in value;
+}
+export function isActionRef(value: unknown): value is ActionRef {
+  return typeof value === "object" && value !== null && "$action" in value;
+}
+export function isDeriveRef(value: unknown): value is DeriveRef {
+  return typeof value === "object" && value !== null && "$derive" in value;
+}