@almadar/ui 6.10.0 → 6.11.0

package/dist/verificationRegistry-BLsjb1oU.d.cts

@@ -0,0 +1,110 @@
+import { D as DrawableNode } from './paintDispatch-CK5uwYEq.cjs';
+import { OrbitalVerificationAPI, TraitStateSnapshot, EventPayload, BusEvent, VerificationCheck, BridgeHealth, VerificationSnapshot, VerificationSummary, TransitionTrace, ServerResponseTrace, EffectTrace, CheckStatus, AssetLoadStatus } from '@almadar/core';
+
+/**
+ * Verification Registry - Tracks runtime verification checks and transition traces
+ *
+ * Provides:
+ * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
+ * 2. A full transition timeline with effect execution results
+ * 3. ServerBridge health snapshot
+ * 4. window.__orbitalVerification for Playwright/automation
+ *
+ * @packageDocumentation
+ */
+
+type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+type TraitSnapshotGetter = () => TraitStateSnapshot;
+declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+declare function getAllChecks(): VerificationCheck[];
+declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+declare function getTransitions(): TransitionTrace[];
+declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+/**
+ * Record a server response as a timeline entry.
+ * Creates a synthetic transition entry with type "server-response" to show
+ * what the server returned (clientEffects, data counts, emitted events).
+ *
+ * `effectResults` — the server's persist/set/call-service outcomes, already
+ * mapped to `EffectTrace` by the caller — populate `entry.effects` so a
+ * denied or failed persist is visible on this synthetic entry too. Before
+ * this it was always `[]`: the ONLY entry the driver's per-event
+ * `server:<orbital>` lookup (`default-snapshot.ts`'s `lastEffectResultsFor`)
+ * can find carried nothing.
+ */
+declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp"> & {
+    effectResults?: EffectTrace[];
+}): void;
+declare function updateBridgeHealth(health: BridgeHealth): void;
+declare function getBridgeHealth(): BridgeHealth | null;
+declare function getSummary(): VerificationSummary;
+declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+declare function getTraitSnapshots(): TraitStateSnapshot[];
+declare function subscribeToVerification(listener: ChangeListener): () => void;
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
+/**
+ * Bind the EventBus so automation can send events and log emissions.
+ * Call this during app initialization.
+ */
+declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Bind a reader for the last drawables list received by a canvas host.
+ * Lets verification scripts inspect exactly which neutral descriptors reached
+ * the painter without re-deriving them from state.
+ */
+declare function bindLastDrawables(getDrawables: () => DrawableNode[] | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+declare function clearVerification(): void;
+
+export { type TraitSnapshotGetter as T, bindEventBus as a, bindCanvasCapture as b, bindLastDrawables as c, bindTraitStateGetter as d, clearVerification as e, getBridgeHealth as f, getAllChecks as g, getSnapshot as h, getSummary as i, getTraitSnapshots as j, getTransitions as k, getTransitionsForTrait as l, recordTransition as m, registerCheck as n, registerTraitSnapshot as o, updateBridgeHealth as p, updateCheck as q, recordServerResponse as r, subscribeToVerification as s, updateAssetStatus as u, waitForTransition as w };

package/dist/verificationRegistry-D8bHWD8Q.d.ts

@@ -0,0 +1,110 @@
+import { D as DrawableNode } from './paintDispatch-CK5uwYEq.js';
+import { OrbitalVerificationAPI, TraitStateSnapshot, EventPayload, BusEvent, VerificationCheck, BridgeHealth, VerificationSnapshot, VerificationSummary, TransitionTrace, ServerResponseTrace, EffectTrace, CheckStatus, AssetLoadStatus } from '@almadar/core';
+
+/**
+ * Verification Registry - Tracks runtime verification checks and transition traces
+ *
+ * Provides:
+ * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
+ * 2. A full transition timeline with effect execution results
+ * 3. ServerBridge health snapshot
+ * 4. window.__orbitalVerification for Playwright/automation
+ *
+ * @packageDocumentation
+ */
+
+type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+type TraitSnapshotGetter = () => TraitStateSnapshot;
+declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+declare function getAllChecks(): VerificationCheck[];
+declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+declare function getTransitions(): TransitionTrace[];
+declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+/**
+ * Record a server response as a timeline entry.
+ * Creates a synthetic transition entry with type "server-response" to show
+ * what the server returned (clientEffects, data counts, emitted events).
+ *
+ * `effectResults` — the server's persist/set/call-service outcomes, already
+ * mapped to `EffectTrace` by the caller — populate `entry.effects` so a
+ * denied or failed persist is visible on this synthetic entry too. Before
+ * this it was always `[]`: the ONLY entry the driver's per-event
+ * `server:<orbital>` lookup (`default-snapshot.ts`'s `lastEffectResultsFor`)
+ * can find carried nothing.
+ */
+declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp"> & {
+    effectResults?: EffectTrace[];
+}): void;
+declare function updateBridgeHealth(health: BridgeHealth): void;
+declare function getBridgeHealth(): BridgeHealth | null;
+declare function getSummary(): VerificationSummary;
+declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+declare function getTraitSnapshots(): TraitStateSnapshot[];
+declare function subscribeToVerification(listener: ChangeListener): () => void;
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
+/**
+ * Bind the EventBus so automation can send events and log emissions.
+ * Call this during app initialization.
+ */
+declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Bind a reader for the last drawables list received by a canvas host.
+ * Lets verification scripts inspect exactly which neutral descriptors reached
+ * the painter without re-deriving them from state.
+ */
+declare function bindLastDrawables(getDrawables: () => DrawableNode[] | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+declare function clearVerification(): void;
+
+export { type TraitSnapshotGetter as T, bindEventBus as a, bindCanvasCapture as b, bindLastDrawables as c, bindTraitStateGetter as d, clearVerification as e, getBridgeHealth as f, getAllChecks as g, getSnapshot as h, getSummary as i, getTraitSnapshots as j, getTransitions as k, getTransitionsForTrait as l, recordTransition as m, registerCheck as n, registerTraitSnapshot as o, updateBridgeHealth as p, updateCheck as q, recordServerResponse as r, subscribeToVerification as s, updateAssetStatus as u, waitForTransition as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "6.10.0",
+  "version": "6.11.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [
@@ -118,12 +118,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.86.0",
-    "@almadar/evaluator": "^2.44.0",
+    "@almadar/core": "^10.87.0",
+    "@almadar/evaluator": "^2.45.0",
     "@almadar/logger": "^1.12.0",
-    "@almadar/runtime": "^6.71.0",
-    "@almadar/std": "^16.207.0",
-    "@almadar/syntax": "^1.16.0",
+    "@almadar/runtime": "^6.72.0",
+    "@almadar/std": "^16.208.0",
+    "@almadar/syntax": "^1.17.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -174,7 +174,7 @@
     }
   },
   "devDependencies": {
-    "@almadar/eslint-plugin": "^2.17.0",
+    "@almadar/eslint-plugin": "^2.18.0",
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.6.0",
     "@react-three/postprocessing": "3.0.4",

package/dist/types-B3nHgnMG.d.cts

@@ -1,51 +0,0 @@
-import { AssetUrl } from '@almadar/core';
-
-/**
- * Cross-cutting atom-level prop shapes shared across the design system.
- */
-
-/**
- * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
- * names that every component in the design system understands.  Prefer this
- * over a bare `string` for any `color` or `variant` prop.
- */
-type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
-/**
- * Concrete error-state shape read by display components (`error.message`,
- * occasionally `error.stack`). Structurally assignable from the global `Error`,
- * so existing call sites passing an `Error` keep working — this just gives the
- * pattern extractor a readable field schema instead of the opaque `Error` global.
- */
-type UiError = {
-    message: string;
-    name?: string;
-    code?: string;
-    stack?: string;
-};
-/**
- * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
- * PricingCard) for their primary/secondary call-to-action props.
- */
-type LinkAction = {
-    label: string;
-    href: string;
-};
-/** An image with its required alt text. */
-type ImageSource = {
-    src: AssetUrl;
-    alt: string;
-};
-/** A 2D point in canvas/layout coordinates. */
-type Point = {
-    x: number;
-    y: number;
-};
-/** A 2D rectangle in canvas coordinates (`w`/`h` = width/height). */
-type Rect = {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-};
-
-export type { ColorToken as C, ImageSource as I, LinkAction as L, Point as P, Rect as R, UiError as U };

package/dist/types-B3nHgnMG.d.ts

@@ -1,51 +0,0 @@
-import { AssetUrl } from '@almadar/core';
-
-/**
- * Cross-cutting atom-level prop shapes shared across the design system.
- */
-
-/**
- * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
- * names that every component in the design system understands.  Prefer this
- * over a bare `string` for any `color` or `variant` prop.
- */
-type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
-/**
- * Concrete error-state shape read by display components (`error.message`,
- * occasionally `error.stack`). Structurally assignable from the global `Error`,
- * so existing call sites passing an `Error` keep working — this just gives the
- * pattern extractor a readable field schema instead of the opaque `Error` global.
- */
-type UiError = {
-    message: string;
-    name?: string;
-    code?: string;
-    stack?: string;
-};
-/**
- * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
- * PricingCard) for their primary/secondary call-to-action props.
- */
-type LinkAction = {
-    label: string;
-    href: string;
-};
-/** An image with its required alt text. */
-type ImageSource = {
-    src: AssetUrl;
-    alt: string;
-};
-/** A 2D point in canvas/layout coordinates. */
-type Point = {
-    x: number;
-    y: number;
-};
-/** A 2D rectangle in canvas coordinates (`w`/`h` = width/height). */
-type Rect = {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-};
-
-export type { ColorToken as C, ImageSource as I, LinkAction as L, Point as P, Rect as R, UiError as U };