@hypen-space/core 0.5.2 → 0.5.3

package/dist/a11y.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 declare function logA11yDiagnostics(diags: A11yDiagnostic[]): string[];
+/**
+ * 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 declare const EXPECTED_A11Y_RULES: readonly string[];
+/** 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 declare function checkRuleDrift(engine: {
+    a11yRules?: () => string[];
+} | null | undefined): A11yRuleDrift;

package/dist/index.d.ts

@@ -80,3 +80,5 @@ export { Logger, createLogger, logger, log, frameworkLoggers, setLogLevel, getLo
 export type { LogLevel, LoggerConfig, LogHandler } from "./logger.js";
 export { validatePatches } from "./validate.js";
 export type { PatchValidationResult } from "./validate.js";
+export { logA11yDiagnostics, checkRuleDrift, EXPECTED_A11Y_RULES } from "./a11y.js";
+export type { A11yDiagnostic, A11ySourceSpan, A11yRuleDrift } from "./a11y.js";

package/dist/index.js

@@ -132,6 +132,47 @@ function validatePatches(patches, knownTypes) {
   }
   return { unknownTypes: [...unknown] };
 }
+// src/a11y.ts
+function logA11yDiagnostics(diags) {
+  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;
+}
+var EXPECTED_A11Y_RULES = [
+  "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"
+];
+function checkRuleDrift(engine) {
+  if (typeof engine?.a11yRules !== "function") {
+    return { hasRuleList: false, missing: [...EXPECTED_A11Y_RULES] };
+  }
+  let advertised;
+  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))
+  };
+}
 export {
   withRetry,
   validatePatches,
@@ -152,6 +193,7 @@ export {
   mapErr,
   map,
   logger,
+  logA11yDiagnostics,
   log,
   item,
   isStateProxy,
@@ -184,6 +226,7 @@ export {
   configureLogger,
   compositeDisposable,
   classifyEngineError,
+  checkRuleDrift,
   batchStateUpdates,
   app,
   all,
@@ -208,6 +251,7 @@ export {
   HypenAppBuilder,
   HypenApp,
   Err,
+  EXPECTED_A11Y_RULES,
   DisposableStack,
   DisposableMixin,
   DataSourceManager,
@@ -218,4 +262,4 @@ export {
   ActionError
 };
 
-//# debugId=14404B08846A6FEF64756E2164756E21
+//# debugId=316C720E20393D9564756E2164756E21

package/dist/index.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/validate.ts"],
+  "sources": ["../src/validate.ts", "../src/a11y.ts"],
   "sourcesContent": [
-    "/**\n * Patch-stream validation. A `create` patch whose `elementType` is neither a\n * known primitive nor a resolved component is a silent resolver miss — the\n * renderer drops the node, no error surfaces. `validatePatches` turns that into\n * a one-line test/CI assertion.\n */\n\nimport type { Patch } from \"./types.js\";\n\nexport interface PatchValidationResult {\n  /** Distinct `create` `elementType`s not in `knownTypes` (i.e. dropped nodes). */\n  unknownTypes: string[];\n}\n\n/**\n * Distinct `create` `elementType`s not in `knownTypes`.\n *\n * `knownTypes` is caller-supplied (engine primitives + the app's resolvable\n * component names) rather than read from the engine: the wasm-bindgen build\n * exposes no primitive list, and hardcoding the built-ins would drift from Rust.\n */\nexport function validatePatches(\n  patches: Patch[],\n  knownTypes: Iterable<string>,\n): PatchValidationResult {\n  const known = knownTypes instanceof Set ? knownTypes : new Set(knownTypes);\n  const unknown = new Set<string>();\n\n  for (const patch of patches) {\n    if (patch.type !== \"create\") continue;\n    const elementType = patch.elementType;\n    if (typeof elementType !== \"string\") continue;\n    if (!known.has(elementType)) unknown.add(elementType);\n  }\n\n  return { unknownTypes: [...unknown] };\n}\n"
+    "/**\n * Patch-stream validation. A `create` patch whose `elementType` is neither a\n * known primitive nor a resolved component is a silent resolver miss — the\n * renderer drops the node, no error surfaces. `validatePatches` turns that into\n * a one-line test/CI assertion.\n */\n\nimport type { Patch } from \"./types.js\";\n\nexport interface PatchValidationResult {\n  /** Distinct `create` `elementType`s not in `knownTypes` (i.e. dropped nodes). */\n  unknownTypes: string[];\n}\n\n/**\n * Distinct `create` `elementType`s not in `knownTypes`.\n *\n * `knownTypes` is caller-supplied (engine primitives + the app's resolvable\n * component names) rather than read from the engine: the wasm-bindgen build\n * exposes no primitive list, and hardcoding the built-ins would drift from Rust.\n */\nexport function validatePatches(\n  patches: Patch[],\n  knownTypes: Iterable<string>,\n): PatchValidationResult {\n  const known = knownTypes instanceof Set ? knownTypes : new Set(knownTypes);\n  const unknown = new Set<string>();\n\n  for (const patch of patches) {\n    if (patch.type !== \"create\") continue;\n    const elementType = patch.elementType;\n    if (typeof elementType !== \"string\") continue;\n    if (!known.has(elementType)) unknown.add(elementType);\n  }\n\n  return { unknownTypes: [...unknown] };\n}\n",
+    "/**\n * Accessibility conformance diagnostics — host-side surfacing.\n *\n * The engine's dev-mode conformance pass (`checkAccessibility(source)` on the\n * WASM engine, wired through the package `Engine` wrappers) returns findings\n * as `A11yDiagnostic[]`. This module provides a small, pure helper for\n * surfacing those findings in a dev console.\n */\n\n/**\n * Byte range `[start, end)` of an element's name token in its source string.\n * Mirrors the Rust `SourceSpan` serialization.\n */\nexport interface A11ySourceSpan {\n  start: number;\n  end: number;\n}\n\n/**\n * A single accessibility conformance finding produced by the engine.\n *\n * Shape mirrors the Rust located-diagnostic serialization\n * (`{ rule, elementType, message, span?, line?, col? }`). The location\n * fields are present when the engine binding ships span support and the\n * finding maps to a source element; older bindings omit them.\n */\nexport interface A11yDiagnostic {\n  /** Kebab-case rule identifier (e.g. `\"icon-only-control\"`). */\n  rule: string;\n  /** The element type the finding applies to (e.g. `\"Button\"`). */\n  elementType: string;\n  /** Human-readable description of the gap. */\n  message: string;\n  /** Byte span of the offending element's name token in the source. */\n  span?: A11ySourceSpan;\n  /** 1-based source line of the finding. */\n  line?: number;\n  /** 1-based column in Unicode codepoints (human/CLI convention). */\n  col?: number;\n}\n\n/**\n * `console.warn` each accessibility finding as\n * `a11y[<rule>] <elementType>: <message>`.\n *\n * Pure with respect to its input (it mutates nothing and returns the\n * formatted lines), so it is unit-testable: the returned array is exactly\n * what was warned, in order. A `console`-less environment is tolerated — the\n * lines are still returned.\n */\nexport function logA11yDiagnostics(diags: A11yDiagnostic[]): string[] {\n  const lines = diags.map(\n    (d) => `a11y[${d.rule}] ${d.elementType}: ${d.message}`,\n  );\n  if (typeof console !== \"undefined\" && typeof console.warn === \"function\") {\n    for (const line of lines) {\n      console.warn(line);\n    }\n  }\n  return lines;\n}\n\n/**\n * Kebab-case ids of every accessibility rule this SDK version expects the\n * engine's conformance pass to implement. Mirrors the engine's `A11yRule`\n * enum via `ALL_RULES` in `hypen-engine-rs/src/ir/conformance.rs` (the Rust\n * side pins these exact strings in a unit test).\n *\n * Used for rule-set drift detection: a prebuilt WASM that predates a rule\n * still exposes `checkAccessibility` and looks current while silently never\n * firing the newer rule.\n */\nexport const EXPECTED_A11Y_RULES: readonly string[] = [\n  \"missing-accessible-name\",\n  \"image-missing-alt\",\n  \"heading-missing-level\",\n  \"nested-interactive\",\n  \"form-control-missing-label\",\n  \"unknown-role-token\",\n  \"unknown-dir-token\",\n  \"dangling-reference\",\n  \"duplicate-id\",\n  \"tablist-wiring-skipped\",\n  \"non-portable-aria\",\n  \"unknown-live-token\",\n  \"unknown-ignore-rule\",\n];\n\n/** Result of {@link checkRuleDrift}. */\nexport interface A11yRuleDrift {\n  /**\n   * Whether the binding exposes `a11yRules()` at all. `false` means the\n   * build predates rule-list stamping entirely (every expected rule is\n   * reported missing).\n   */\n  hasRuleList: boolean;\n  /** Expected rule ids the binding does not implement; empty means no drift. */\n  missing: string[];\n}\n\n/**\n * Compare an engine binding's advertised accessibility rules against\n * {@link EXPECTED_A11Y_RULES}. `engine` is anything exposing the WASM\n * binding surface (a raw `WasmEngine` or a wrapper forwarding `a11yRules`).\n *\n * Drift is a warning, not a failure: findings from the rules the binding\n * does implement remain valid, so callers should surface the missing rules\n * and continue rather than abort the check.\n */\nexport function checkRuleDrift(\n  engine: { a11yRules?: () => string[] } | null | undefined,\n): A11yRuleDrift {\n  if (typeof engine?.a11yRules !== \"function\") {\n    return { hasRuleList: false, missing: [...EXPECTED_A11Y_RULES] };\n  }\n  let advertised: string[];\n  try {\n    advertised = engine.a11yRules();\n  } catch {\n    return { hasRuleList: false, missing: [...EXPECTED_A11Y_RULES] };\n  }\n  const have = new Set(advertised);\n  return {\n    hasRuleList: true,\n    missing: EXPECTED_A11Y_RULES.filter((rule) => !have.has(rule)),\n  };\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBO,SAAS,eAAe,CAC7B,SACA,YACuB;AAAA,EACvB,MAAM,QAAQ,sBAAsB,MAAM,aAAa,IAAI,IAAI,UAAU;AAAA,EACzE,MAAM,UAAU,IAAI;AAAA,EAEpB,WAAW,SAAS,SAAS;AAAA,IAC3B,IAAI,MAAM,SAAS;AAAA,MAAU;AAAA,IAC7B,MAAM,cAAc,MAAM;AAAA,IAC1B,IAAI,OAAO,gBAAgB;AAAA,MAAU;AAAA,IACrC,IAAI,CAAC,MAAM,IAAI,WAAW;AAAA,MAAG,QAAQ,IAAI,WAAW;AAAA,EACtD;AAAA,EAEA,OAAO,EAAE,cAAc,CAAC,GAAG,OAAO,EAAE;AAAA;",
-  "debugId": "14404B08846A6FEF64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBO,SAAS,eAAe,CAC7B,SACA,YACuB;AAAA,EACvB,MAAM,QAAQ,sBAAsB,MAAM,aAAa,IAAI,IAAI,UAAU;AAAA,EACzE,MAAM,UAAU,IAAI;AAAA,EAEpB,WAAW,SAAS,SAAS;AAAA,IAC3B,IAAI,MAAM,SAAS;AAAA,MAAU;AAAA,IAC7B,MAAM,cAAc,MAAM;AAAA,IAC1B,IAAI,OAAO,gBAAgB;AAAA,MAAU;AAAA,IACrC,IAAI,CAAC,MAAM,IAAI,WAAW;AAAA,MAAG,QAAQ,IAAI,WAAW;AAAA,EACtD;AAAA,EAEA,OAAO,EAAE,cAAc,CAAC,GAAG,OAAO,EAAE;AAAA;;ACe/B,SAAS,kBAAkB,CAAC,OAAmC;AAAA,EACpE,MAAM,QAAQ,MAAM,IAClB,CAAC,MAAM,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAChD;AAAA,EACA,IAAI,OAAO,YAAY,eAAe,OAAO,QAAQ,SAAS,YAAY;AAAA,IACxE,WAAW,QAAQ,OAAO;AAAA,MACxB,QAAQ,KAAK,IAAI;AAAA,IACnB;AAAA,EACF;AAAA,EACA,OAAO;AAAA;AAaF,IAAM,sBAAyC;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAuBO,SAAS,cAAc,CAC5B,QACe;AAAA,EACf,IAAI,OAAO,QAAQ,cAAc,YAAY;AAAA,IAC3C,OAAO,EAAE,aAAa,OAAO,SAAS,CAAC,GAAG,mBAAmB,EAAE;AAAA,EACjE;AAAA,EACA,IAAI;AAAA,EACJ,IAAI;AAAA,IACF,aAAa,OAAO,UAAU;AAAA,IAC9B,MAAM;AAAA,IACN,OAAO,EAAE,aAAa,OAAO,SAAS,CAAC,GAAG,mBAAmB,EAAE;AAAA;AAAA,EAEjE,MAAM,OAAO,IAAI,IAAI,UAAU;AAAA,EAC/B,OAAO;AAAA,IACL,aAAa;AAAA,IACb,SAAS,oBAAoB,OAAO,CAAC,SAAS,CAAC,KAAK,IAAI,IAAI,CAAC;AAAA,EAC/D;AAAA;",
+  "debugId": "316C720E20393D9564756E2164756E21",
   "names": []
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/core",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Hypen core - Platform-agnostic reactive UI runtime (types, state, router, events)",
   "type": "module",
   "main": "./dist/index.js",

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/index.ts

@@ -331,3 +331,8 @@ export type { LogLevel, LoggerConfig, LogHandler } from "./logger.js";
 // 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/types.ts

@@ -28,10 +28,22 @@ export type Patch = {
     | "attachEvent"
     | "detachEvent"
     | "detach"
-    | "attach";
+    | "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;
@@ -40,6 +52,124 @@ export type Patch = {
   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;