@async/framework 0.11.15 → 0.11.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.11.15",
+  "version": "0.11.17",
   "description": "No-build Loader app runtime with browser and server entrypoints, signals, command events, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "sideEffects": false,
@@ -60,6 +60,21 @@
       "import": "./server.js",
       "default": "./server.js"
     },
+    "./runtime": {
+      "types": "./runtime.d.ts",
+      "import": "./runtime.js",
+      "default": "./runtime.js"
+    },
+    "./runtime/signals": {
+      "types": "./runtime/signals.d.ts",
+      "import": "./runtime/signals.js",
+      "default": "./runtime/signals.js"
+    },
+    "./runtime/events": {
+      "types": "./runtime/events.d.ts",
+      "import": "./runtime/events.js",
+      "default": "./runtime/events.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -75,6 +90,13 @@
     "framework.d.ts",
     "framework.ts",
     "package.json",
-    "server.js"
+    "server.js",
+    "runtime.d.ts",
+    "runtime/signals.d.ts",
+    "runtime/events.d.ts",
+    "runtime.js",
+    "runtime/signals.js",
+    "runtime/events.js",
+    "runtime/shared.js"
   ]
 }

package/runtime/events.d.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/runtime/events.
+
+export type ElementLocator = string | { readonly selector: string; readonly optional?: boolean };
+export type EventRuntimeContext = {
+  event: Event;
+  element: Element;
+  el: Element;
+  root: ParentNode;
+  signals?: { set(path: string, value: unknown): void };
+};
+export type EventValueSource =
+  | readonly ["event.target.value"]
+  | readonly ["event.target.checked"]
+  | readonly ["constant", value: unknown];
+export type EventCommand =
+  | readonly ["handler", id: string]
+  | readonly ["preventDefault"]
+  | readonly ["stopPropagation"]
+  | readonly ["stopImmediatePropagation"]
+  | readonly ["setSignal", path: string, valueSource: EventValueSource];
+export type EventBindingRecord = readonly [element: number, event: string, commands: readonly EventCommand[]];
+export type StrictHandlerDescriptor = {
+  readonly mode?: "strict";
+  readonly module?: string;
+  readonly browserImport: string;
+  readonly exportName: string;
+  readonly version?: string;
+  readonly integrity?: string;
+};
+export type HandlerDescriptor = ((context: EventRuntimeContext) => unknown | Promise<unknown>) | StrictHandlerDescriptor;
+export type EventRuntimePlan = {
+  readonly version?: 1;
+  readonly events: readonly EventBindingRecord[];
+  readonly handlers?: Record<string, HandlerDescriptor>; 
+};
+export type EventRuntimeOptions = {
+  readonly elements?: readonly ElementLocator[];
+  readonly signal?: AbortSignal;
+  readonly signals?: { set(path: string, value: unknown): void };
+  readonly importModule?: (specifier: string) => Promise<Record<string, unknown>>;
+  readonly onDiagnostic?: (diagnostic: Record<string, unknown>) => void;
+};
+export type EventRuntimeController = {
+  readonly stopped: boolean;
+  stop(): void;
+};
+export declare function startEvents(rootOrOptions: ParentNode | ({ root: ParentNode; plan: EventRuntimePlan } & EventRuntimeOptions), plan?: EventRuntimePlan, options?: EventRuntimeOptions): EventRuntimeController;

package/runtime/events.js

@@ -0,0 +1,208 @@
+import {
+  createRuntimeController,
+  normalizeRuntimeStartArgs,
+  resolveElements
+} from "./shared.js";
+
+export function startEvents(rootOrOptions, planArg, optionsArg) {
+  const { root, plan, options } = normalizeRuntimeStartArgs(rootOrOptions, planArg, optionsArg);
+  assertEventPlan(plan);
+  assertHandlers(plan.handlers ?? {});
+  const runtimeOptions = {
+    ...options,
+    root,
+    moduleCache: new Map()
+  };
+  const elements = options.resolvedElements ?? resolveElements(root, options.elements ?? [], {
+    onDiagnostic: options.onDiagnostic
+  });
+  const listeners = [];
+  let stopped = false;
+
+  try {
+    const bindingsByType = groupEventBindings(plan.events, elements);
+    for (const [eventType, bindings] of bindingsByType) {
+      const listener = (event) => {
+        void dispatchPlannedEvent(event, bindings, plan.handlers ?? {}, runtimeOptions);
+      };
+      root.addEventListener(eventType, listener);
+      listeners.push([eventType, listener]);
+    }
+  } catch (error) {
+    for (const [eventType, listener] of listeners) {
+      root.removeEventListener(eventType, listener);
+    }
+    throw error;
+  }
+
+  return createRuntimeController({
+    get stopped() {
+      return stopped;
+    },
+    stop() {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      for (const [eventType, listener] of listeners.splice(0).reverse()) {
+        root.removeEventListener(eventType, listener);
+      }
+    }
+  }, options.signal);
+}
+
+function assertEventPlan(plan) {
+  if (!plan || typeof plan !== "object") {
+    throw new TypeError("Event runtime plan must be an object.");
+  }
+  if (plan.version !== undefined && plan.version !== 1) {
+    throw new Error(`Unsupported event runtime plan version: ${String(plan.version)}.`);
+  }
+  if (!Array.isArray(plan.events)) {
+    throw new TypeError("Event runtime plan requires an events array.");
+  }
+}
+
+function groupEventBindings(records, elements) {
+  const groups = new Map();
+  for (const record of records) {
+    const [elementIndex, eventType, commands] = assertEventBinding(record);
+    const element = elements[elementIndex];
+    if (!element) {
+      throw new Error(`Event binding target ${elementIndex} was not resolved.`);
+    }
+    if (!groups.has(eventType)) {
+      groups.set(eventType, []);
+    }
+    groups.get(eventType).push({ element, commands });
+  }
+  return groups;
+}
+
+function assertEventBinding(record) {
+  if (!Array.isArray(record) || record.length !== 3) {
+    throw new TypeError("Event binding records must be [element, event, commands].");
+  }
+  const [elementIndex, eventType, commands] = record;
+  if (!Number.isInteger(elementIndex) || elementIndex < 0) {
+    throw new TypeError("Event binding element index must be a non-negative integer.");
+  }
+  if (typeof eventType !== "string" || eventType.length === 0) {
+    throw new TypeError("Event binding event type must be a non-empty string.");
+  }
+  if (!Array.isArray(commands)) {
+    throw new TypeError("Event binding commands must be an array.");
+  }
+  return record;
+}
+
+async function dispatchPlannedEvent(event, bindings, handlers, options) {
+  for (const binding of bindings) {
+    if (!event.composedPath?.().includes(binding.element) && !binding.element.contains(event.target)) {
+      continue;
+    }
+    for (const command of binding.commands) {
+      const result = await runCommand(command, event, binding.element, handlers, options);
+      if (result === "stop-immediate") {
+        return;
+      }
+    }
+  }
+}
+
+async function runCommand(command, event, element, handlers, options) {
+  if (!Array.isArray(command) || typeof command[0] !== "string") {
+    throw new TypeError("Event command must be a tuple with a command name.");
+  }
+
+  switch (command[0]) {
+    case "preventDefault":
+      event.preventDefault();
+      return;
+    case "stopPropagation":
+      event.stopPropagation();
+      return;
+    case "stopImmediatePropagation":
+      event.stopImmediatePropagation();
+      return "stop-immediate";
+    case "setSignal":
+      if (!options.signals || typeof options.signals.set !== "function") {
+        throw new Error("setSignal command requires a signal runtime controller.");
+      }
+      options.signals?.set(command[1], readEventValue(event, command[2]));
+      return;
+    case "handler": {
+      const handler = await resolveHandler(command[1], handlers, options);
+      await handler({ event, element, el: element, root: options.root, signals: options.signals });
+      return;
+    }
+    default:
+      throw new Error(`Unsupported event command: ${command[0]}.`);
+  }
+}
+
+function readEventValue(event, source) {
+  if (!Array.isArray(source)) {
+    throw new TypeError("Event value source must be a tuple.");
+  }
+  switch (source[0]) {
+    case "event.target.value":
+      return event.target?.value;
+    case "event.target.checked":
+      return Boolean(event.target?.checked);
+    case "constant":
+      return source[1];
+    default:
+      throw new Error(`Unsupported event value source: ${source[0]}.`);
+  }
+}
+
+async function resolveHandler(id, handlers, options) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Handler command requires a non-empty id.");
+  }
+  const descriptor = handlers[id];
+  if (typeof descriptor === "function") {
+    return descriptor;
+  }
+  assertStrictDescriptor(id, descriptor);
+  const importModule = options.importModule ?? ((specifier) => import(specifier));
+  if (!options.moduleCache.has(descriptor.browserImport)) {
+    options.moduleCache.set(descriptor.browserImport, importModule(descriptor.browserImport));
+  }
+  const module = await options.moduleCache.get(descriptor.browserImport);
+  const handler = module?.[descriptor.exportName];
+  if (typeof handler !== "function") {
+    throw new TypeError(`Strict handler "${id}" did not resolve export "${descriptor.exportName}".`);
+  }
+  return handler;
+}
+
+function assertHandlers(handlers) {
+  for (const [id, descriptor] of Object.entries(handlers)) {
+    if (typeof descriptor !== "function") {
+      assertStrictDescriptor(id, descriptor);
+    }
+  }
+}
+
+function assertStrictDescriptor(id, descriptor) {
+  if (!descriptor || typeof descriptor !== "object") {
+    throw new TypeError(`Handler "${id}" must be a function or strict descriptor.`);
+  }
+  if (descriptor.mode !== undefined && descriptor.mode !== "strict") {
+    throw new TypeError(`Handler "${id}" must use a strict descriptor.`);
+  }
+  if (typeof descriptor.browserImport !== "string" || descriptor.browserImport.length === 0) {
+    throw new TypeError(`Handler "${id}" requires browserImport.`);
+  }
+  if (typeof descriptor.exportName !== "string" || descriptor.exportName.length === 0) {
+    throw new TypeError(`Handler "${id}" requires exportName.`);
+  }
+  if (descriptor.version !== undefined) {
+    const url = new URL(descriptor.browserImport, "https://async.local/");
+    if (url.searchParams.get("v") !== String(descriptor.version)) {
+      throw new TypeError(`Handler "${id}" browserImport must include version query v=${descriptor.version}.`);
+    }
+  }
+}

package/runtime/shared.js

@@ -0,0 +1,85 @@
+export function createRuntimeController(controller, signal) {
+  if (signal) {
+    if (signal.aborted) {
+      controller.stop();
+    } else {
+      signal.addEventListener("abort", () => controller.stop(), { once: true });
+    }
+  }
+  return controller;
+}
+
+export function normalizeRuntimeStartArgs(rootOrOptions, planArg, optionsArg) {
+  if (rootOrOptions && typeof rootOrOptions === "object" && "root" in rootOrOptions) {
+    return {
+      root: requireRoot(rootOrOptions.root),
+      plan: rootOrOptions.plan,
+      options: {
+        ...rootOrOptions.options,
+        ...withoutKeys(rootOrOptions, ["root", "plan", "options"])
+      }
+    };
+  }
+
+  return {
+    root: requireRoot(rootOrOptions),
+    plan: planArg,
+    options: optionsArg ?? {}
+  };
+}
+
+export function resolveElements(root, locators, options = {}) {
+  if (!Array.isArray(locators)) {
+    throw new TypeError("Runtime element locators must be an array.");
+  }
+  return locators.map((locator, index) => resolveElement(root, locator, index, options));
+}
+
+function resolveElement(root, locator, index, options) {
+  const record = normalizeLocator(locator);
+  const element = root.querySelector(record.selector);
+  if (!element && !record.optional) {
+    throw new Error(`Runtime locator ${index} did not match: ${record.selector}`);
+  }
+  if (!element) {
+    options.onDiagnostic?.({
+      type: "missing-optional-locator",
+      index,
+      selector: record.selector
+    });
+  }
+  return element;
+}
+
+function normalizeLocator(locator) {
+  if (typeof locator === "string") {
+    return { selector: locator, optional: false };
+  }
+  if (locator && typeof locator === "object" && typeof locator.selector === "string") {
+    return {
+      selector: locator.selector,
+      optional: Boolean(locator.optional)
+    };
+  }
+  throw new TypeError("Runtime element locator must be a selector string or selector record.");
+}
+
+function requireRoot(root) {
+  if (!root || typeof root.querySelector !== "function") {
+    throw new TypeError("Runtime root must be a Document, Element, or DocumentFragment with querySelector.");
+  }
+  if (typeof root.addEventListener !== "function") {
+    throw new TypeError("Runtime root must support addEventListener.");
+  }
+  return root;
+}
+
+function withoutKeys(source, keys) {
+  const result = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (!keys.includes(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/runtime/signals.d.ts

@@ -0,0 +1,31 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/runtime/signals.
+
+export type ElementLocator = string | { readonly selector: string; readonly optional?: boolean };
+export type SignalRuntimePlan = {
+  readonly version?: 1;
+  readonly values?: readonly (readonly [path: string, value: unknown])[];
+  readonly bindings?: readonly SignalBindingRecord[];
+};
+export type SignalBindingRecord =
+  | readonly [element: number, kind: "text", path: string]
+  | readonly [element: number, kind: "value", path: string]
+  | readonly [element: number, kind: "attr", name: string, path: string]
+  | readonly [element: number, kind: "prop", name: string, path: string]
+  | readonly [element: number, kind: "class", token: string, path: string]
+  | readonly [element: number, kind: "classList", path: string];
+export type SignalRuntimeOptions = {
+  readonly elements?: readonly ElementLocator[];
+  readonly signal?: AbortSignal;
+  readonly onDiagnostic?: (diagnostic: Record<string, unknown>) => void;
+};
+export type SignalRuntimeController = {
+  readonly stopped: boolean;
+  stop(): void;
+  get(path: string): unknown;
+  set(path: string, value: unknown): void;
+  update(path: string, fn: (value: unknown) => unknown): unknown;
+  subscribe(path: string, fn: (value: unknown) => void): () => void;
+  snapshot(): Record<string, unknown>;
+};
+export declare function startSignals(rootOrOptions: ParentNode | ({ root: ParentNode; plan: SignalRuntimePlan } & SignalRuntimeOptions), plan?: SignalRuntimePlan, options?: SignalRuntimeOptions): SignalRuntimeController;

package/runtime/signals.js

@@ -0,0 +1,209 @@
+import {
+  createRuntimeController,
+  normalizeRuntimeStartArgs,
+  resolveElements
+} from "./shared.js";
+
+export function startSignals(rootOrOptions, planArg, optionsArg) {
+  const { root, plan, options } = normalizeRuntimeStartArgs(rootOrOptions, planArg, optionsArg);
+  assertSignalPlan(plan);
+  const store = new Map();
+  const subscribers = new Map();
+  const cleanups = [];
+  let stopped = false;
+
+  for (const [path, value] of plan.values ?? []) {
+    assertPath(path);
+    store.set(path, value);
+  }
+
+  const elements = options.resolvedElements ?? resolveElements(root, options.elements ?? [], {
+    onDiagnostic: options.onDiagnostic
+  });
+
+  try {
+    for (const binding of plan.bindings ?? []) {
+      cleanups.push(bindSignal(binding, elements, { get, subscribe }));
+    }
+  } catch (error) {
+    for (const cleanup of cleanups.splice(0).reverse()) {
+      cleanup();
+    }
+    throw error;
+  }
+
+  const controller = createRuntimeController({
+    get stopped() {
+      return stopped;
+    },
+    get,
+    set,
+    update,
+    subscribe,
+    snapshot,
+    stop() {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      for (const cleanup of cleanups.splice(0).reverse()) {
+        cleanup();
+      }
+      subscribers.clear();
+    }
+  }, options.signal);
+
+  return controller;
+
+  function get(path) {
+    assertPath(path);
+    return store.get(path);
+  }
+
+  function set(path, value) {
+    assertOpen();
+    assertPath(path);
+    if (Object.is(store.get(path), value)) {
+      return;
+    }
+    store.set(path, value);
+    for (const fn of subscribers.get(path) ?? []) {
+      fn(value);
+    }
+  }
+
+  function update(path, fn) {
+    if (typeof fn !== "function") {
+      throw new TypeError("update(path, fn) requires a function.");
+    }
+    const next = fn(get(path));
+    set(path, next);
+    return next;
+  }
+
+  function subscribe(path, fn) {
+    assertOpen();
+    assertPath(path);
+    if (typeof fn !== "function") {
+      throw new TypeError("subscribe(path, fn) requires a function.");
+    }
+    if (!subscribers.has(path)) {
+      subscribers.set(path, new Set());
+    }
+    subscribers.get(path).add(fn);
+    return () => {
+      subscribers.get(path)?.delete(fn);
+    };
+  }
+
+  function snapshot() {
+    return Object.fromEntries(store);
+  }
+
+  function assertOpen() {
+    if (stopped) {
+      throw new Error("Signal runtime controller has stopped.");
+    }
+  }
+}
+
+function assertSignalPlan(plan) {
+  if (!plan || typeof plan !== "object") {
+    throw new TypeError("Signal runtime plan must be an object.");
+  }
+  if (plan.version !== undefined && plan.version !== 1) {
+    throw new Error(`Unsupported signal runtime plan version: ${String(plan.version)}.`);
+  }
+}
+
+function bindSignal(record, elements, signals) {
+  const [elementIndex, kind, ...args] = assertSignalBinding(record);
+  const element = elements[elementIndex];
+  if (!element) {
+    throw new Error(`Signal binding target ${elementIndex} was not resolved.`);
+  }
+  const path = args.at(-1);
+  const apply = () => applyBinding(element, kind, args, signals.get(path));
+  apply();
+  return signals.subscribe(path, apply);
+}
+
+function assertSignalBinding(record) {
+  if (!Array.isArray(record) || record.length < 3) {
+    throw new TypeError("Signal binding records must be tuple arrays.");
+  }
+  const [elementIndex, kind] = record;
+  if (!Number.isInteger(elementIndex) || elementIndex < 0) {
+    throw new TypeError("Signal binding element index must be a non-negative integer.");
+  }
+  if (!["text", "value", "attr", "prop", "class", "classList"].includes(kind)) {
+    throw new Error(`Unsupported signal binding kind: ${String(kind)}.`);
+  }
+  return record;
+}
+
+function applyBinding(element, kind, args, value) {
+  switch (kind) {
+    case "text":
+      element.textContent = stringify(value);
+      return;
+    case "value":
+      if ("value" in element) {
+        element.value = value ?? "";
+      } else {
+        applyAttribute(element, "value", value);
+      }
+      return;
+    case "attr":
+      applyAttribute(element, args[0], value);
+      return;
+    case "prop":
+      element[args[0]] = value;
+      return;
+    case "class":
+      element.classList.toggle(args[0], Boolean(value));
+      return;
+    case "classList":
+      applyClassList(element, value);
+      return;
+    default:
+      throw new Error(`Unsupported signal binding kind: ${String(kind)}.`);
+  }
+}
+
+function applyAttribute(element, name, value) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("Attribute signal binding requires an attribute name.");
+  }
+  if (value === false || value === null || value === undefined) {
+    element.removeAttribute(name);
+    return;
+  }
+  if (value === true) {
+    element.setAttribute(name, "");
+    return;
+  }
+  element.setAttribute(name, String(value));
+}
+
+function applyClassList(element, value) {
+  const previous = element.__asyncRuntimeClassList ?? new Set();
+  for (const token of previous) {
+    element.classList.remove(token);
+  }
+  const next = new Set(String(value ?? "").split(/\s+/).filter(Boolean));
+  for (const token of next) {
+    element.classList.add(token);
+  }
+  element.__asyncRuntimeClassList = next;
+}
+
+function assertPath(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new TypeError("Signal path must be a non-empty string.");
+  }
+}
+
+function stringify(value) {
+  return value === null || value === undefined ? "" : String(value);
+}

package/runtime.d.ts

@@ -0,0 +1,72 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/runtime.
+
+export type ElementLocator = string | { readonly selector: string; readonly optional?: boolean };
+export type RuntimeSliceController = {
+  readonly stopped: boolean;
+  stop(): void;
+};
+export type SignalRuntimePlan = {
+  readonly version?: 1;
+  readonly values?: readonly (readonly [path: string, value: unknown])[];
+  readonly bindings?: readonly SignalBindingRecord[];
+};
+export type SignalBindingRecord =
+  | readonly [element: number, kind: "text", path: string]
+  | readonly [element: number, kind: "value", path: string]
+  | readonly [element: number, kind: "attr", name: string, path: string]
+  | readonly [element: number, kind: "prop", name: string, path: string]
+  | readonly [element: number, kind: "class", token: string, path: string]
+  | readonly [element: number, kind: "classList", path: string];
+export type EventRuntimePlan = {
+  readonly version?: 1;
+  readonly events: readonly EventBindingRecord[];
+  readonly handlers?: Record<string, HandlerDescriptor>;
+};
+export type EventBindingRecord = readonly [element: number, event: string, commands: readonly EventCommand[]];
+export type EventCommand =
+  | readonly ["handler", id: string]
+  | readonly ["preventDefault"]
+  | readonly ["stopPropagation"]
+  | readonly ["stopImmediatePropagation"]
+  | readonly ["setSignal", path: string, valueSource: EventValueSource];
+export type EventValueSource =
+  | readonly ["event.target.value"]
+  | readonly ["event.target.checked"]
+  | readonly ["constant", value: unknown];
+export type EventRuntimeContext = {
+  event: Event;
+  element: Element;
+  el: Element;
+  root: ParentNode;
+  signals?: SignalRuntimeController;
+};
+export type StrictHandlerDescriptor = {
+  readonly mode?: "strict";
+  readonly module?: string;
+  readonly browserImport: string;
+  readonly exportName: string;
+  readonly version?: string;
+  readonly integrity?: string;
+};
+export type HandlerDescriptor = ((context: EventRuntimeContext) => unknown | Promise<unknown>) | StrictHandlerDescriptor;
+export type RuntimePlan = {
+  readonly version: 1;
+  readonly elements?: readonly ElementLocator[];
+  readonly signals?: SignalRuntimePlan;
+  readonly events?: EventRuntimePlan;
+};
+export type RuntimeStartOptions = {
+  readonly signal?: AbortSignal;
+  readonly importModule?: (specifier: string) => Promise<Record<string, unknown>>;
+  readonly onDiagnostic?: (diagnostic: Record<string, unknown>) => void;
+};
+export type SignalRuntimeController = RuntimeSliceController & {
+  get(path: string): unknown;
+  set(path: string, value: unknown): void;
+  update(path: string, fn: (value: unknown) => unknown): unknown;
+  subscribe(path: string, fn: (value: unknown) => void): () => void;
+  snapshot(): Record<string, unknown>;
+};
+export type RuntimeController = RuntimeSliceController;
+export declare function start(rootOrOptions: ParentNode | ({ root: ParentNode; plan: RuntimePlan } & RuntimeStartOptions), plan?: RuntimePlan, options?: RuntimeStartOptions): RuntimeController;