@hypen-space/core 0.4.980 → 0.5.3

package/dist/types.d.ts

@@ -16,10 +16,21 @@ export type Patch = {
      * rebuild. If `remove` arrives for a detached id instead, the
      * subtree is torn down normally.
      */
-    type: "create" | "setProp" | "removeProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent" | "detach" | "attach";
+    type: "create" | "setProp" | "removeProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent" | "detach" | "attach" | "setSemantics";
     id?: string;
     elementType?: string;
     props?: Record<string, any>;
+    /**
+     * Accessibility semantics derived by the engine for this node. Carried on
+     * `create` (first paint) and on `setSemantics` (reactive change — a
+     * templated accessible name or bound state whose source path changed).
+     * A `setSemantics` always carries the node's **complete** resolved block;
+     * renderers re-apply it with the same translation they run at create,
+     * clearing anything the new block no longer sets. Absent on `create` when
+     * the node has nothing derivable; absent on `setSemantics` when the node
+     * lost all semantics (→ clear everything).
+     */
+    semantics?: Semantics;
     name?: string;
     value?: any;
     text?: string;
@@ -27,6 +38,123 @@ export type Patch = {
     beforeId?: string;
     eventName?: string;
 };
+/**
+ * Platform-neutral accessibility semantics for a node, derived in the engine
+ * and carried on `create` patches. Each renderer maps this onto its native
+ * accessibility model (ARIA attributes on DOM, `Modifier.semantics` on
+ * Compose, accessibility traits on SwiftUI).
+ *
+ * Every field is optional; an absent field means "nothing derivable".
+ */
+export type Semantics = {
+    /**
+     * What this node is, as a platform-neutral role token (e.g. `"button"`).
+     * Mirrors the ARIA role vocabulary. Emitted only where the role is
+     * structurally certain from the component type.
+     */
+    role?: string;
+    /** Heading level (1–6) when known. */
+    level?: number;
+    /** Whether the node represents in-progress content (maps to `aria-busy`). */
+    busy?: boolean;
+    /**
+     * Live-region politeness (`.liveRegion("polite" | "assertive")`) →
+     * `aria-live` on DOM and the Canvas shadow tree. The engine validates the
+     * token, so only those two values arrive. Travels untranslated to the
+     * native renderers (no direct analog wired yet).
+     */
+    live?: string;
+    /**
+     * Accessible name derived from the element's text content, for roles that
+     * require one. On DOM this is usually left unapplied — the browser derives
+     * the name from visible content — but renderers without that affordance
+     * (Canvas shadow tree, iOS, Android) use it directly.
+     */
+    name?: string;
+    /**
+     * `true` when the element's role requires a name but none could be derived
+     * (e.g. an icon-only button). Surfaced by dev-mode conformance checks; the
+     * fix is an explicit label.
+     */
+    nameMissing?: boolean;
+    /**
+     * `true` when {@link name} came from an explicit author `.label(...)` rather
+     * than derived content. DOM applies an explicit name as `aria-label` (an
+     * intentional override) but leaves a derived name to the visible content.
+     */
+    nameExplicit?: boolean;
+    /**
+     * `true` when the element was marked decorative via `.hidden()`. It is
+     * removed from the accessibility tree (`aria-hidden`).
+     */
+    hidden?: boolean;
+    /**
+     * Supplementary description (`.description(...)`) — extra context beyond the
+     * name. Applied as `aria-description` on DOM.
+     */
+    description?: string;
+    /** Disclosure state → `aria-expanded`. */
+    expanded?: boolean;
+    /** Toggle-button state → `aria-pressed`. */
+    pressed?: boolean;
+    /** Selected state (e.g. a tab) → `aria-selected`. */
+    selected?: boolean;
+    /** Current-item token (page/step/…) → `aria-current`. */
+    current?: string;
+    /**
+     * Checked state for a `Checkbox`/`Switch` bound via `.bind(@state.x)` →
+     * `aria-checked`. Resolved at reconcile from the control's bind-target value.
+     */
+    checked?: boolean;
+    /**
+     * Validity state for a form control (`.invalid(bool | @state.hasError)`) →
+     * `aria-invalid`. A bound value resolves at reconcile and stays live via
+     * `setSemantics` re-emits. DOM only for now.
+     */
+    invalid?: boolean;
+    /**
+     * Cross-node relationship: id of the element this node controls →
+     * `aria-controls`. Web-leaning (DOM only); id references do not survive to
+     * the string-hint native APIs. See the guide's "Platform support" section
+     * (`hypen-docs/content/docs/guide/accessibility.mdx`).
+     */
+    controls?: string;
+    /**
+     * Cross-node relationship: id of the element that describes this node →
+     * `aria-describedby`. Web-leaning (DOM only), as with `controls`.
+     */
+    describedby?: string;
+    /**
+     * The author-supplied stable id of this node (`.id("details-panel")`) —
+     * the anchor id-reference relationships resolve against. Applied as the
+     * DOM `id` attribute.
+     */
+    id?: string;
+    /**
+     * Cross-node relationship: id of the element that labels this node →
+     * `aria-labelledby` (the tabpanel→tab half of the Tabs pattern). DOM only.
+     */
+    labelledby?: string;
+    /**
+     * Reactive cross-node reference: id of the currently-active descendant →
+     * `aria-activedescendant` (the roving focus pointer of composite widgets).
+     * Usually bound (`.activedescendant(@state.focusedId)`); kept live via
+     * `setSemantics` re-emits. DOM only.
+     */
+    activeDescendant?: string;
+    /**
+     * Cross-node relationship: id of an element that is logically this node's
+     * child but rendered elsewhere (a portaled popup) → `aria-owns`. DOM only.
+     */
+    owns?: string;
+    /**
+     * Base text direction (`.dir("rtl" | "ltr" | "auto")`) → the HTML `dir`
+     * attribute on DOM. The engine validates the token, so only those three
+     * values arrive. Native renderers translate to their layout-direction
+     * APIs (follow-up; the value already travels on the block).
+     */
+    dir?: string;
+};
 export type Action = {
     name: string;
     payload?: any;

package/dist/validate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Patch-stream validation. A `create` patch whose `elementType` is neither a
+ * known primitive nor a resolved component is a silent resolver miss — the
+ * renderer drops the node, no error surfaces. `validatePatches` turns that into
+ * a one-line test/CI assertion.
+ */
+import type { Patch } from "./types.js";
+export interface PatchValidationResult {
+    /** Distinct `create` `elementType`s not in `knownTypes` (i.e. dropped nodes). */
+    unknownTypes: string[];
+}
+/**
+ * Distinct `create` `elementType`s not in `knownTypes`.
+ *
+ * `knownTypes` is caller-supplied (engine primitives + the app's resolvable
+ * component names) rather than read from the engine: the wasm-bindgen build
+ * exposes no primitive list, and hardcoding the built-ins would drift from Rust.
+ */
+export declare function validatePatches(patches: Patch[], knownTypes: Iterable<string>): PatchValidationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/core",
-  "version": "0.4.980",
+  "version": "0.5.3",
   "description": "Hypen core - Platform-agnostic reactive UI runtime (types, state, router, events)",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,12 @@
       "import": "./dist/router.js",
       "default": "./dist/router.js"
     },
+    "./managed-router": {
+      "types": "./dist/managed-router.d.ts",
+      "bun": "./src/managed-router.ts",
+      "import": "./dist/managed-router.js",
+      "default": "./dist/managed-router.js"
+    },
     "./events": {
       "types": "./dist/events.d.ts",
       "bun": "./src/events.ts",
@@ -106,6 +112,12 @@
       "import": "./dist/engine-base.js",
       "default": "./dist/engine-base.js"
     },
+    "./persistence": {
+      "types": "./dist/persistence.d.ts",
+      "bun": "./src/persistence.ts",
+      "import": "./dist/persistence.js",
+      "default": "./dist/persistence.js"
+    },
     "./portable": {
       "types": "./dist/portable.d.ts",
       "bun": "./src/portable.ts",

package/src/a11y.ts

@@ -0,0 +1,127 @@
+/**
+ * Accessibility conformance diagnostics — host-side surfacing.
+ *
+ * The engine's dev-mode conformance pass (`checkAccessibility(source)` on the
+ * WASM engine, wired through the package `Engine` wrappers) returns findings
+ * as `A11yDiagnostic[]`. This module provides a small, pure helper for
+ * surfacing those findings in a dev console.
+ */
+
+/**
+ * Byte range `[start, end)` of an element's name token in its source string.
+ * Mirrors the Rust `SourceSpan` serialization.
+ */
+export interface A11ySourceSpan {
+  start: number;
+  end: number;
+}
+
+/**
+ * A single accessibility conformance finding produced by the engine.
+ *
+ * Shape mirrors the Rust located-diagnostic serialization
+ * (`{ rule, elementType, message, span?, line?, col? }`). The location
+ * fields are present when the engine binding ships span support and the
+ * finding maps to a source element; older bindings omit them.
+ */
+export interface A11yDiagnostic {
+  /** Kebab-case rule identifier (e.g. `"icon-only-control"`). */
+  rule: string;
+  /** The element type the finding applies to (e.g. `"Button"`). */
+  elementType: string;
+  /** Human-readable description of the gap. */
+  message: string;
+  /** Byte span of the offending element's name token in the source. */
+  span?: A11ySourceSpan;
+  /** 1-based source line of the finding. */
+  line?: number;
+  /** 1-based column in Unicode codepoints (human/CLI convention). */
+  col?: number;
+}
+
+/**
+ * `console.warn` each accessibility finding as
+ * `a11y[<rule>] <elementType>: <message>`.
+ *
+ * Pure with respect to its input (it mutates nothing and returns the
+ * formatted lines), so it is unit-testable: the returned array is exactly
+ * what was warned, in order. A `console`-less environment is tolerated — the
+ * lines are still returned.
+ */
+export function logA11yDiagnostics(diags: A11yDiagnostic[]): string[] {
+  const lines = diags.map(
+    (d) => `a11y[${d.rule}] ${d.elementType}: ${d.message}`,
+  );
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    for (const line of lines) {
+      console.warn(line);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Kebab-case ids of every accessibility rule this SDK version expects the
+ * engine's conformance pass to implement. Mirrors the engine's `A11yRule`
+ * enum via `ALL_RULES` in `hypen-engine-rs/src/ir/conformance.rs` (the Rust
+ * side pins these exact strings in a unit test).
+ *
+ * Used for rule-set drift detection: a prebuilt WASM that predates a rule
+ * still exposes `checkAccessibility` and looks current while silently never
+ * firing the newer rule.
+ */
+export const EXPECTED_A11Y_RULES: readonly string[] = [
+  "missing-accessible-name",
+  "image-missing-alt",
+  "heading-missing-level",
+  "nested-interactive",
+  "form-control-missing-label",
+  "unknown-role-token",
+  "unknown-dir-token",
+  "dangling-reference",
+  "duplicate-id",
+  "tablist-wiring-skipped",
+  "non-portable-aria",
+  "unknown-live-token",
+  "unknown-ignore-rule",
+];
+
+/** Result of {@link checkRuleDrift}. */
+export interface A11yRuleDrift {
+  /**
+   * Whether the binding exposes `a11yRules()` at all. `false` means the
+   * build predates rule-list stamping entirely (every expected rule is
+   * reported missing).
+   */
+  hasRuleList: boolean;
+  /** Expected rule ids the binding does not implement; empty means no drift. */
+  missing: string[];
+}
+
+/**
+ * Compare an engine binding's advertised accessibility rules against
+ * {@link EXPECTED_A11Y_RULES}. `engine` is anything exposing the WASM
+ * binding surface (a raw `WasmEngine` or a wrapper forwarding `a11yRules`).
+ *
+ * Drift is a warning, not a failure: findings from the rules the binding
+ * does implement remain valid, so callers should surface the missing rules
+ * and continue rather than abort the check.
+ */
+export function checkRuleDrift(
+  engine: { a11yRules?: () => string[] } | null | undefined,
+): A11yRuleDrift {
+  if (typeof engine?.a11yRules !== "function") {
+    return { hasRuleList: false, missing: [...EXPECTED_A11Y_RULES] };
+  }
+  let advertised: string[];
+  try {
+    advertised = engine.a11yRules();
+  } catch {
+    return { hasRuleList: false, missing: [...EXPECTED_A11Y_RULES] };
+  }
+  const have = new Set(advertised);
+  return {
+    hasRuleList: true,
+    missing: EXPECTED_A11Y_RULES.filter((rule) => !have.has(rule)),
+  };
+}

package/src/engine-base.ts

@@ -46,6 +46,35 @@ import type {
 
 const log = frameworkLoggers.engine;
 
+/**
+ * Recursively convert wasm-bindgen `Map` values into plain objects.
+ *
+ * The web-target WASM returns action payloads (and nested values) as `Map`
+ * instances; user handlers expect plain objects. Only plain objects
+ * (`constructor === Object`), arrays, and Maps are descended into — class
+ * instances, `Date`, etc. are passed through untouched.
+ */
+function mapToPlainObject(value: any): any {
+  if (value instanceof Map) {
+    const obj: Record<string, any> = {};
+    for (const [key, val] of value.entries()) {
+      obj[key] = mapToPlainObject(val);
+    }
+    return obj;
+  }
+  if (Array.isArray(value)) {
+    return value.map(mapToPlainObject);
+  }
+  if (value && typeof value === "object" && value.constructor === Object) {
+    const obj: Record<string, any> = {};
+    for (const [key, val] of Object.entries(value)) {
+      obj[key] = mapToPlainObject(val);
+    }
+    return obj;
+  }
+  return value;
+}
+
 /**
  * Shared base wrapping a wasm-bindgen `WasmEngine`. `any` here is load-
  * bearing: the concrete type is `WasmEngine` from either the `wasm-node`
@@ -57,6 +86,16 @@ export abstract class BaseEngine {
   protected wasmEngine: any = null;
   protected initialized = false;
 
+  /**
+   * Component names the resolver was asked for and returned `null` on — i.e.
+   * names that are neither a registered primitive (the engine checks those
+   * first and never consults the resolver for them) nor resolvable to a
+   * template. Each such name produces an opaque `Create` patch the renderer
+   * drops. Tracked so a miss is warned about once and can be asserted on in
+   * tests. See `getUnresolvedComponents`.
+   */
+  private unresolvedComponents = new Set<string>();
+
   /**
    * Initialize the WASM module. Platform-specific.
    *
@@ -98,16 +137,47 @@ export abstract class BaseEngine {
 
   /**
    * Set the component resolver for dynamic component composition.
+   *
+   * The resolver is wrapped to detect "resolver misses": the engine only
+   * consults the resolver for element types that are NOT registered
+   * primitives, so a `null` return means the name resolves to nothing and
+   * the engine will emit an opaque `Create` the renderer silently drops
+   * (e.g. an anonymous component that never got registered). The first miss
+   * for each unique name is logged with actionable guidance; every miss is
+   * recorded for `getUnresolvedComponents()` / test assertions.
    */
   setComponentResolver(resolver: ComponentResolver): void {
     const engine = this.ensureInitialized();
     engine.setComponentResolver(
       (componentName: string, contextPath: string | null) => {
-        return resolver(componentName, contextPath);
+        const resolved = resolver(componentName, contextPath);
+        if (resolved == null) {
+          if (!this.unresolvedComponents.has(componentName)) {
+            this.unresolvedComponents.add(componentName);
+            log.warn(
+              `Component "${componentName}" did not resolve: it is not a ` +
+                `registered primitive and the component resolver returned null. ` +
+                `The engine will emit an opaque Create for it and the renderer ` +
+                `will drop it. Did you forget to register/.module(...) the ` +
+                `component, or is its name misspelled in the template?`,
+            );
+          }
+        }
+        return resolved;
       },
     );
   }
 
+  /**
+   * Names the component resolver has been asked for and failed to resolve
+   * this session (see `setComponentResolver`). Useful as a CI / smoke-test
+   * assertion — an empty array means every referenced component resolved to
+   * a primitive or a template.
+   */
+  getUnresolvedComponents(): string[] {
+    return [...this.unresolvedComponents];
+  }
+
   /**
    * Parse and render Hypen DSL source code.
    * @throws {ParseError} if the source fails to parse
@@ -220,11 +290,24 @@ export abstract class BaseEngine {
 
   /**
    * Platform hook: normalize an incoming action before the user handler
-   * sees it. Default identity; subclasses can override to unwrap native
-   * values (e.g. browser Maps in action payloads).
+   * sees it.
+   *
+   * The default converts any `Map` instances in the payload into plain
+   * objects (deeply). This is the landmine the wasm-bindgen **web** target
+   * sets: it returns structured action payloads as JS `Map`s, so a handler
+   * reading `payload.to` gets `undefined` and `@router.push, to: "/x"`
+   * silently no-ops. Every consumer of the web-target WASM — the browser
+   * engine, a Cloudflare `CFEngine`, any future runtime — inherits the fix
+   * here instead of rediscovering it.
+   *
+   * The wasm-bindgen **bundler** (node) target already returns plain
+   * objects, so for it this is a harmless deep walk. Subclasses on that
+   * target may override with an identity to skip the walk (see
+   * `@hypen-space/server`).
    */
   protected normalizeAction(action: Action): Action {
-    return action;
+    if (!action.payload) return action;
+    return { ...action, payload: mapToPlainObject(action.payload) };
   }
 
   /**

package/src/index.ts

@@ -326,3 +326,13 @@ export {
   isDebugMode,
 } from "./logger.js";
 export type { LogLevel, LoggerConfig, LogHandler } from "./logger.js";
+
+// Patch-stream validation — catch silent resolver misses (opaque component
+// elementTypes) in CI / smoke tests off the wire.
+export { validatePatches } from "./validate.js";
+export type { PatchValidationResult } from "./validate.js";
+
+// Accessibility conformance diagnostics — surface the engine's dev-mode
+// `checkAccessibility(source)` findings in a host dev console.
+export { logA11yDiagnostics, checkRuleDrift, EXPECTED_A11Y_RULES } from "./a11y.js";
+export type { A11yDiagnostic, A11ySourceSpan, A11yRuleDrift } from "./a11y.js";

package/src/remote/index.ts

@@ -44,3 +44,19 @@ export type {
 
 // Re-export Patch type
 export type { Patch } from "../types.js";
+
+// Transport-agnostic remote session. The engine is injected via
+// `SessionHost.createEngine`, so any runtime (Node/Bun, Cloudflare Durable
+// Objects, etc.) can reuse the Hypen remote protocol envelope.
+// `@hypen-space/server` re-exports these for back-compat.
+export {
+  RemoteSession,
+  AsyncQueueTransport,
+  createBunWebSocketTransport,
+} from "./remote-session.js";
+export type {
+  SessionTransport,
+  SessionHost,
+  RemoteSessionOptions,
+  OutgoingMessage,
+} from "./remote-session.js";