stylegallery 0.1.0

package/recipes/primitive-to-recipe-matrix.md

@@ -0,0 +1,83 @@
+---
+type: Planning Guide
+title: Primitive To Recipe Matrix
+description: Matrix that explains which layout primitives each screen recipe uses, why the slot exists, and what risk follows from substitution.
+---
+
+# Primitive To Recipe Matrix
+
+Use this matrix before selecting a recipe or generating a visual reference. It shows which primitives are part of each recipe, which slots are structural, and which slots can be replaced when the content model asks for a different spatial behavior.
+
+Legend:
+
+- `E` = essential: removing or replacing this primitive changes the recipe's spatial model.
+- `H` = helper: supports rhythm, grouping, or local readability without defining the screen type by itself.
+- `S` = substitutable: useful default, but another primitive may fit the same recipe slot when content constraints differ.
+- `-` = not part of the recommended recipe stack.
+
+## Recipe Pattern Matrix
+
+| Recipe | `stack` | `box` | `center` | `cluster` | `content-limiter` | `super-center` | `icon-frame` | `frame` | `cover` | `sidebar` | `switcher` | `media-object` | `split-nav` | `holy-grail` | `sticky-footer` | `sticky-header` | `scroll-body-shell` | `fixed-sidenav-shell` | `sticky-aside` | `ram-grid` | `card-grid` | `twelve-span-grid` | `page-grid` | `grid-wrapper` | `columns` | `deconstructed-pancake` | `line-up` | `clamped-card` | `fluid-styles` | `split-screen` | `list-detail` | `supporting-pane` | `feed` | `breadcrumb` | `pagination` | `badge-list` | `step-nav` | `tab-strip` | `reel` | `imposter` | `panel-layout` | `overlay-stack` | `wrap-row` | `dense-grid` | `masonry-approx` | `main-with-rail` |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| [Homepage](homepage.md) | H | - | - | H | E | - | - | S | E | - | - | - | - | - | - | - | - | - | - | S | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [SaaS settings](saas-settings.md) | H | - | - | - | E | - | - | - | - | - | - | - | - | - | - | - | - | E | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [Dashboard](dashboard.md) | - | - | - | H | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | E | - | E | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [Article page](article-page.md) | H | - | - | - | E | - | - | - | - | - | - | - | - | - | - | - | - | - | S | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [List detail](list-detail.md) | H | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | H | - | - | - | - | - | - | - | - | - | - | - | - | - | E | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [Form flow](form-flow.md) | E | - | - | H | E | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| [Command surface](command-surface.md) | - | - | - | - | - | - | - | - | - | - | - | - | H | - | - | - | E | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | E | - | - | - |
+
+## Slot Classification Table
+
+| Recipe | Pattern stack | Essential slots | Helper slots | Substitutable slots | Source lineage and semantic risk |
+| --- | --- | --- | --- | --- | --- |
+| [Homepage](homepage.md) | `cover`, `content-limiter`, `stack`, `cluster`, `ram-grid`, `frame` | `cover`, `content-limiter` | `stack`, `cluster` | `ram-grid`, `frame` | Local webpage synthesis from homepage section jobs, with Every Layout influence for cover/stack/cluster and MDN grid/media constraints. Risk: replacing `cover` or `content-limiter` weakens the first-viewport hook or readable explanation path; replacing `ram-grid`/`frame` is acceptable when proof or media content has a different shape. |
+| [SaaS settings](saas-settings.md) | `fixed-sidenav-shell`, `content-limiter`, `stack` | `fixed-sidenav-shell`, `content-limiter` | `stack` | - | Local settings synthesis, with Material-style settings navigation and MDN sticky/overflow mechanics. Risk: replacing the shell changes scroll ownership and wayfinding; replacing `content-limiter` makes form-like settings harder to scan. |
+| [Dashboard](dashboard.md) | `page-grid`, `card-grid`, `cluster` | `page-grid`, `card-grid` | `cluster` | - | Material dashboard layout and MDN grid lineage. Risk: replacing `page-grid` or `card-grid` removes comparable panel alignment; `cluster` can be adjusted only when action groups still wrap safely. |
+| [Article page](article-page.md) | `content-limiter`, `sticky-aside`, `stack` | `content-limiter` | `stack` | `sticky-aside` | Every Layout sidebar/stack influence and MDN sticky positioning. Risk: replacing `content-limiter` harms readable measure; replacing `sticky-aside` is acceptable when supplemental content must remain in normal reading order. |
+| [List detail](list-detail.md) | `list-detail`, `scroll-body-shell`, `stack` | `list-detail` | `scroll-body-shell`, `stack` | - | Local split-view synthesis, with Material master-detail patterns and MDN overflow mechanics. Risk: replacing `list-detail` changes the browse-and-inspect contract; shell behavior must preserve clear scroll ownership. |
+| [Form flow](form-flow.md) | `content-limiter`, `stack`, `cluster` | `content-limiter`, `stack` | `cluster` | - | GOV.UK-style form sequencing with Every Layout stack/cluster influence. Risk: replacing `content-limiter` or `stack` breaks the single-column completion path; action grouping can vary only if labels and errors remain adjacent. |
+| [Command surface](command-surface.md) | `scroll-body-shell`, `split-nav`, `wrap-row` | `scroll-body-shell`, `wrap-row` | `split-nav` | - | Local command-surface synthesis, with MDN overflow/flex wrapping mechanics. Risk: replacing `scroll-body-shell` destabilizes command/content regions; replacing `wrap-row` can create overflow or hidden controls. |
+
+## Lineage And Risk Notes
+
+### Homepage
+
+The homepage recipe is local synthesis: it maps raw webpage content into hook, explanation, proof, comparison, conversion, and navigation jobs before visual styling. `cover` and `content-limiter` are essential because they protect first-viewport framing and readable copy. `ram-grid` and `frame` are substitutable when repeated proof or media should use `card-grid`, `columns`, or no media slot.
+
+### SaaS settings
+
+The SaaS settings recipe combines fixed navigation with a constrained settings column. `fixed-sidenav-shell` and `content-limiter` are essential because they define stable wayfinding and readable edit sections. The main semantic risk is accidental independent scrolling inside settings groups, which can separate labels, help text, errors, and controls.
+
+### Dashboard
+
+The dashboard recipe comes from page-level grid alignment and repeated panel comparison. `page-grid` and `card-grid` are essential because users scan across comparable cards and panels. `cluster` is a helper for filters and actions; it can be replaced with `wrap-row` when command density grows.
+
+### Article page
+
+The article recipe prioritizes reading measure before supplemental layout. `content-limiter` is essential; `sticky-aside` is substitutable because some supporting content should remain inline for source-order or narrow-screen reasons. The main risk is letting the aside become a second reading path that competes with the article.
+
+### List detail
+
+The list-detail recipe is a task model, not just a split screen. `list-detail` is essential because it defines peer list and detail regions with a selected item relationship. `scroll-body-shell` is a helper when the viewport owns a stable shell, but the recipe still has to name whether the list, detail, or page owns scrolling.
+
+### Form flow
+
+The form flow recipe is a sequential completion path. `content-limiter` and `stack` are essential because they keep groups readable and preserve vertical task progression. `cluster` is a helper for actions that need to wrap before overflow.
+
+### Command surface
+
+The command surface recipe is local synthesis for tool-heavy shells. `scroll-body-shell` is essential because command regions should remain stable while content changes. `wrap-row` is essential because controls must remain reachable under long labels and narrow widths; `split-nav` is a helper for separating command groups.
+
+## Substitution Rules
+
+- Substitute `ram-grid` with `card-grid`, `columns`, or `masonry-approx` only after naming the repeated content shape and scan behavior.
+- Substitute `sticky-aside` with normal inline `stack` content when supporting material must be read in sequence.
+- Substitute `cluster` with `wrap-row` when controls have longer labels or stronger overflow risk.
+- Do not substitute `content-limiter` out of reading, form, or homepage explanation sections unless another primitive preserves readable measure.
+- Do not substitute `scroll-body-shell`, `fixed-sidenav-shell`, or `list-detail` without renaming scroll ownership and focus-return behavior.
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/saas-settings.md

@@ -0,0 +1,52 @@
+---
+type: Layout Recipe
+title: SaaS Settings
+description: Compose a fixed side navigation with a constrained settings flow.
+screen_type: SaaS settings
+primary_user_task: Review and edit account or workspace settings.
+spatial_model: Fixed navigation plus constrained primary content.
+---
+
+# SaaS Settings
+
+## Recommended Pattern Stack
+
+- [fixed-sidenav-shell](../patterns/viewport-shell/fixed-sidenav-shell.md)
+- [content-limiter](../patterns/containment/content-limiter.md)
+- [stack](../patterns/stacking/stack.md)
+
+## DOM And Source Order
+
+Place the navigation before the main settings region when it is the first meaningful wayfinding element. Keep each settings section as a semantic section with its own heading.
+
+## Scroll Ownership
+
+The main region owns vertical scrolling. The side navigation remains stable. Avoid adding independent scrolling to individual settings groups unless a group has a named overflow responsibility.
+
+## Accessibility Expectations
+
+- Focus expectation: Side-navigation links move predictably into the matching settings section, and focus remains visible when the main region scrolls.
+- Scroll expectation: The stable navigation must not create a second hidden scroll path; each settings group should rely on the main region unless overflow is declared.
+- Cognitive risk: Settings pages mix navigation and editing; use headings, save-state labels, and grouping so users do not lose the current section.
+
+## Responsive Behavior
+
+At narrow widths, navigation may become an inline region above the main content. Preserve source order and avoid visually reordering sections ahead of their headings.
+
+## Constraints And Change Points
+
+Use a content width token for the settings column and a gutter token for shell spacing. Keep fixed navigation width explicit so the main scroll region has a predictable inline size.
+
+## When Not To Use
+
+Do not use this recipe for a short one-page preference form where document flow and a simple [content-limiter](../patterns/containment/content-limiter.md) are enough.
+
+## Related Patterns
+
+- [scroll-body-shell](../patterns/viewport-shell/scroll-body-shell.md)
+- [supporting-pane](../patterns/split-sidebar/supporting-pane.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/scripts/agent-native/a2a-projection.mjs

@@ -0,0 +1,248 @@
+import { cloneAndFreeze, hashCanonical } from "./canonical-json.mjs";
+
+const STATE_MAP = Object.freeze({
+  PENDING: "submitted", CREATED: "submitted", QUEUED: "submitted", SUBMITTED: "submitted",
+  RUNNING: "working", STARTED: "working", IN_PROGRESS: "working", WORKING: "working",
+  COMPLETED: "completed", SUCCEEDED: "completed", SUCCESS: "completed", DONE: "completed",
+  FAILED: "failed", ERROR: "failed", ERRORED: "failed",
+  CANCELED: "canceled", CANCELLED: "canceled", ABORTED: "canceled",
+  REJECTED: "rejected", AUTH_REQUIRED: "auth-required", AUTHENTICATION_REQUIRED: "auth-required",
+});
+
+const TERMINAL_STATES = new Set(["completed", "failed", "canceled", "rejected", "auth-required"]);
+
+export class A2AProjectionError extends TypeError {
+  constructor(code, message, path = "") {
+    super(message);
+    this.name = "A2AProjectionError";
+    this.code = code;
+    if (path) this.path = path;
+  }
+}
+
+function fail(code, message, path) {
+  throw new A2AProjectionError(code, message, path);
+}
+
+function object(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function pick(value, ...keys) {
+  if (!object(value)) return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key) && value[key] !== undefined) return value[key];
+  return undefined;
+}
+
+function copy(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function freeze(value) {
+  return cloneAndFreeze(value);
+}
+
+function digest(value) {
+  return hashCanonical(value).slice("sha256:".length);
+}
+
+function idOf(value, ...keys) {
+  const id = pick(value, ...keys, "stableRef", "stable_ref", "id");
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+
+function domainTaskId(source, task) {
+  const explicit = idOf(source, "domainTaskId", "domain_task_id");
+  const taskRef = idOf(task, "taskId", "task_id", "stableRef", "stable_ref");
+  const generic = !pick(source, "domainTask", "domain_task") ? idOf(source, "taskId", "task_id") : undefined;
+  return explicit
+    ?? taskRef
+    ?? generic
+    ?? `sg:task/a2a-${digest({ task, message: pick(source, "message") }).slice(0, 20)}`;
+}
+
+function domainRunId(source, run, taskId) {
+  const explicit = idOf(source, "domainRunId", "domain_run_id");
+  const runRef = idOf(run, "runId", "run_id", "stableRef", "stable_ref");
+  const generic = !pick(source, "domainRun", "domain_run") ? idOf(source, "runId", "run_id") : undefined;
+  return explicit
+    ?? runRef
+    ?? generic
+    ?? `sg:run/a2a-${digest({ run, taskId }).slice(0, 20)}`;
+}
+
+function protocolIds(source, task, binding, taskId, runId) {
+  const protocolTaskId = pick(source, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? pick(binding, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? pick(task, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? `a2a-task-${digest({ taskId, runId, message: pick(source, "message"), binding }).slice(0, 24)}`;
+  const protocolContextId = pick(source, "protocolContextId", "protocol_context_id", "a2aContextId", "a2a_context_id")
+    ?? pick(binding, "protocolContextId", "protocol_context_id", "a2aContextId", "a2a_context_id")
+    ?? pick(task, "contextId", "context_id")
+    ?? `a2a-context-${digest({ taskId, runId }).slice(0, 24)}`;
+  if (protocolTaskId === taskId || protocolTaskId === runId) fail("protocol_task_id_conflict", "A2A task ID must not equal a domain Task or Run ID", "protocolTaskId");
+  if (protocolContextId === taskId || protocolContextId === runId || protocolContextId === protocolTaskId) fail("protocol_context_id_conflict", "A2A context ID must remain distinct from domain and task IDs", "protocolContextId");
+  return { protocolTaskId: String(protocolTaskId), protocolContextId: String(protocolContextId) };
+}
+
+function makeBinding(source, task, binding, taskId, runId, protocolTaskId, protocolContextId) {
+  const supplied = object(binding) ? copy(binding) : {};
+  const bindingId = pick(supplied, "bindingId", "binding_id", "protocolBindingId", "protocol_binding_id")
+    ?? `sg:binding/a2a-${digest({ taskId, runId, protocolTaskId, protocolContextId }).slice(0, 24)}`;
+  if (typeof bindingId !== "string" || bindingId.length === 0) fail("protocol_binding_required", "ProtocolBinding requires a non-empty binding ID", "protocolBindingId");
+  if (bindingId === taskId || bindingId === runId || bindingId === protocolTaskId || bindingId === protocolContextId) fail("protocol_binding_id_conflict", "ProtocolBinding ID must remain distinct from every correlated ID", "protocolBindingId");
+  return freeze({
+    ...supplied,
+    bindingId,
+    domainRunId: runId,
+    domainTaskId: taskId,
+    protocol: "a2a",
+    protocolBindingId: bindingId,
+    protocolContextId,
+    protocolTaskId,
+    runId,
+    taskId,
+  });
+}
+
+function taskFrom(input) {
+  const source = object(input) ? input : {};
+  const task = object(source.task) ? source.task : source;
+  return object(task.task) && !pick(task, "status", "id", "contextId") ? task.task : task;
+}
+
+function bindingFrom(input, task) {
+  return pick(input, "protocolBinding", "protocol_binding", "binding")
+    ?? pick(task, "protocolBinding", "protocol_binding", "binding")
+    ?? {};
+}
+
+function domainState(input, task) {
+  const source = object(input) ? input : {};
+  const domainTask = pick(source, "domainTask", "domain_task");
+  return pick(domainTask, "state", "status", "taskState", "task_state")
+    ?? pick(task, "domainState", "domain_state")
+    ?? pick(task, "state", "taskState", "task_state")
+    ?? pick(pick(task, "status"), "state", "status")
+    ?? "UNKNOWN";
+}
+
+function taskStatus(task, state) {
+  const status = object(pick(task, "status")) ? copy(task.status) : {};
+  return { ...status, state };
+}
+
+function responseFor(task) {
+  const { protocolBinding: _binding, ...nested } = task;
+  return freeze({ ...task, task: nested });
+}
+
+function projectTask(input, state, mode = "project") {
+  const source = object(input) ? input : {};
+  const task = taskFrom(source);
+  const domainTask = object(pick(source, "domainTask", "domain_task")) ? pick(source, "domainTask", "domain_task") : task;
+  const run = pick(source, "run", "domainRun", "domain_run");
+  const taskId = domainTaskId(source, domainTask);
+  const runId = domainRunId(source, run, taskId);
+  const suppliedBinding = bindingFrom(source, task);
+  const { protocolTaskId, protocolContextId } = protocolIds(source, task, suppliedBinding, taskId, runId);
+  const binding = makeBinding(source, domainTask, suppliedBinding, taskId, runId, protocolTaskId, protocolContextId);
+  const requestedTaskId = pick(source, "taskId", "task_id");
+  const existingProtocolId = pick(task, "id", "protocolTaskId", "protocol_task_id")
+    ?? (object(pick(task, "status")) ? pick(task, "taskId", "task_id") : undefined);
+  const currentProtocolId = mode === "send" ? protocolTaskId : existingProtocolId ?? protocolTaskId;
+  if (requestedTaskId !== undefined && requestedTaskId !== currentProtocolId && requestedTaskId !== protocolTaskId) fail("protocol_task_mismatch", "requested A2A task ID does not match the correlated task", "taskId");
+  const message = pick(source, "message");
+  const history = Array.isArray(pick(task, "history")) ? copy(task.history) : (message ? [copy(message)] : []);
+  const artifacts = Array.isArray(pick(task, "artifacts")) ? copy(task.artifacts) : [];
+  const projected = {
+    artifacts,
+    contextId: protocolContextId,
+    history,
+    id: currentProtocolId,
+    kind: "task",
+    metadata: {
+      ...(object(pick(task, "metadata")) ? copy(task.metadata) : {}),
+      stylegallery: { domainRunId: runId, domainTaskId: taskId, protocolBindingId: binding.protocolBindingId },
+    },
+    protocolBinding: binding,
+    status: taskStatus(task, state),
+  };
+  if (mode === "send") projected.history = message ? [copy(message)] : history;
+  return freeze(projected);
+}
+
+/** Map every domain lifecycle state to an official A2A TaskState value. */
+export function mapTaskState(value) {
+  const raw = typeof value === "string" ? value : pick(value, "state", "status", "taskState", "task_state");
+  const normalized = String(raw ?? "UNKNOWN").trim().toUpperCase().replaceAll("-", "_").replaceAll(" ", "_");
+  return STATE_MAP[normalized] ?? "unknown";
+}
+
+/** Return the deterministic, v1-shaped Agent Card for StyleGallery. */
+export function createAgentCard(input = {}) {
+  const source = object(input) ? input : {};
+  const skills = [
+    ["discover", "Discover StyleGallery capabilities and immutable manifest."],
+    ["resolve", "Resolve a StableRef or VersionID to its immutable object."],
+    ["claims", "Inspect claims, evidence, validation, and governance disposition."],
+    ["context", "Build a bounded retrieval context package with provenance."],
+    ["ops", "List read-only operation specifications and schemas."],
+    ["retrieve", "Retrieve ranked governed knowledge without mutation."],
+  ].map(([id, description]) => ({ description, examples: [], id, inputModes: ["text", "data"], name: id, outputModes: ["text", "data"], tags: ["stylegallery", "knowledge"] }));
+  return freeze({
+    capabilities: { pushNotifications: false, stateTransitionHistory: true, streaming: false },
+    defaultInputModes: ["text", "data"],
+    defaultOutputModes: ["text", "data"],
+    description: typeof source.description === "string" ? source.description : "Evidence-preserving, agent-native StyleGallery knowledge operations.",
+    name: typeof source.name === "string" ? source.name : "StyleGallery Agent",
+    protocolVersion: "1.0",
+    skills,
+    supportsAuthenticatedExtendedCard: false,
+    url: typeof source.url === "string" ? source.url : "https://stylegallery.local/agent",
+    version: typeof source.version === "string" ? source.version : "1.0.0",
+  });
+}
+
+/** Project an A2A SendMessage request into a new submitted protocol task. */
+export function sendMessage(input) {
+  const source = object(input) ? input : fail("send_message_input_required", "sendMessage expects an object");
+  const message = pick(source, "message");
+  if (!object(message)) fail("message_required", "SendMessage requires a message object", "message");
+  const task = projectTask({ ...source, message }, "submitted", "send");
+  return responseFor(task);
+}
+
+/** Project current domain Task/Run state while preserving the A2A task ID. */
+export function getTask(input) {
+  const source = object(input) ? input : fail("get_task_input_required", "getTask expects an object");
+  const task = taskFrom(source);
+  const taskId = pick(source, "taskId", "task_id");
+  if (taskId === undefined && !idOf(task, "id", "taskId", "task_id", "protocolTaskId", "protocol_task_id")) fail("protocol_task_required", "GetTask requires an A2A task ID", "taskId");
+  const state = mapTaskState(domainState(source, task));
+  const projected = projectTask(source, state);
+  return responseFor(projected);
+}
+
+/** Request cancellation; terminal non-canceled states reject invalid transitions. */
+export function cancelTask(input) {
+  const source = object(input) ? input : fail("cancel_task_input_required", "cancelTask expects an object");
+  const task = taskFrom(source);
+  const current = mapTaskState(domainState(source, task));
+  if (TERMINAL_STATES.has(current) && current !== "canceled") fail("cancellation_not_allowed", `cannot cancel a ${current} A2A task`, "task");
+  if (current === "unknown") fail("invalid_task_transition", "cannot cancel an unknown A2A task state", "task");
+  const projected = projectTask(source, "canceled");
+  return responseFor(projected);
+}
+
+export const buildAgentCard = createAgentCard;
+export const projectAgentCard = createAgentCard;
+export const agentCard = createAgentCard;
+export const projectSendMessage = sendMessage;
+export const handleSendMessage = sendMessage;
+export const projectGetTask = getTask;
+export const handleGetTask = getTask;
+export const projectCancelTask = cancelTask;
+export const handleCancelTask = cancelTask;
+export const projectTaskState = mapTaskState;
+export const toA2ATaskState = mapTaskState;

package/scripts/agent-native/agui-projection.mjs

@@ -0,0 +1,178 @@
+import { canonicalize, cloneAndFreeze, hashCanonical } from "./canonical-json.mjs";
+
+const TERMINAL = new Set(["RUN_FINISHED", "RUN_ERROR"]);
+const EVENT_TYPES = new Set([
+  "RUN_STARTED", "RUN_FINISHED", "RUN_ERROR",
+  "TEXT_MESSAGE_START", "TEXT_MESSAGE_CONTENT", "TEXT_MESSAGE_END",
+  "TOOL_CALL_START", "TOOL_CALL_ARGS", "TOOL_CALL_ARGUMENTS", "TOOL_CALL_END",
+  "STATE_SNAPSHOT", "STATE_DELTA",
+]);
+
+export class AgUiProjectionError extends TypeError {
+  constructor(code, message, path = "") {
+    super(message);
+    this.name = "AgUiProjectionError";
+    this.code = code;
+    if (path) this.path = path;
+  }
+}
+
+function pick(value, ...keys) {
+  if (!value || typeof value !== "object") return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key) && value[key] !== undefined) return value[key];
+  return undefined;
+}
+
+function text(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function domainId(value, ...keys) {
+  return text(pick(value, ...keys, "stable_ref", "stableRef", "id"), "unknown");
+}
+
+function bindingIds(binding, task, run) {
+  const bindingId = text(pick(binding, "binding_id", "bindingId", "protocol_binding_id", "protocolBindingId"), "sg:binding/agui");
+  const taskId = domainId(task, "task_id", "taskId");
+  const runId = domainId(run, "run_id", "runId");
+  const taskProtocolId = text(
+    pick(binding, "agui_task_id", "aguiTaskId", "protocol_task_id", "protocolTaskId", "protocolTask"),
+    `agui-task-${hashCanonical({ bindingId, taskId }).slice(7, 23)}`,
+  );
+  const runProtocolId = text(
+    pick(binding, "agui_run_id", "aguiRunId", "protocol_run_id", "protocolRunId", "protocolRun"),
+    `agui-run-${hashCanonical({ bindingId, runId }).slice(7, 23)}`,
+  );
+  const threadId = text(pick(binding, "thread_id", "threadId", "agui_thread_id", "aguiThreadId"), taskProtocolId);
+  return { bindingId, domainTaskId: taskId, domainRunId: runId, taskProtocolId, runProtocolId, threadId };
+}
+
+function eventType(event) {
+  return String(pick(event, "type", "eventType", "event_type", "name") ?? "")
+    .trim().toUpperCase().replaceAll("-", "_");
+}
+
+function asEvents(input) {
+  if (Array.isArray(input)) return input;
+  return pick(input, "events", "items") ?? null;
+}
+
+function failure(code, message, path) {
+  return path ? { code, message, path } : { code, message };
+}
+
+/** Validate an AG-UI event sequence before it crosses the protocol boundary. */
+export function validateAgUiTransitions(input) {
+  const events = asEvents(input);
+  const failures = [];
+  if (!Array.isArray(events)) return { ok: false, valid: false, failures: [failure("agui_events_required", "events must be an array", "events")] };
+  if (events.length === 0) failures.push(failure("agui_events_empty", "AG-UI event sequence cannot be empty", "events"));
+  let started = false;
+  let ended = false;
+  let openTextId = null;
+  let openToolId = null;
+  let runId = null;
+  let terminalCount = 0;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    const type = eventType(event);
+    const path = `/events/${index}`;
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      failures.push(failure("agui_event_invalid", "event must be an object", path));
+      continue;
+    }
+    if (!EVENT_TYPES.has(type)) failures.push(failure("agui_event_type_invalid", `unsupported AG-UI event type ${type || "<empty>"}`, `${path}/type`));
+    const eventRunId = pick(event, "runId", "run_id");
+    if (eventRunId !== undefined && runId !== null && eventRunId !== runId) failures.push(failure("agui_run_id_mismatch", "all events must use one protocol run ID", `${path}/runId`));
+    if (eventRunId !== undefined) runId = eventRunId;
+    if (ended) failures.push(failure("agui_event_after_terminal", "no event may follow a terminal event", path));
+    if (type === "RUN_STARTED") {
+      if (started) failures.push(failure("agui_run_started_duplicate", "RUN_STARTED may occur only once", path));
+      if (index !== 0) failures.push(failure("agui_run_started_not_first", "RUN_STARTED must be the first event", path));
+      started = true;
+      continue;
+    }
+    if (!started) failures.push(failure("agui_run_not_started", "event cannot precede RUN_STARTED", path));
+    if (TERMINAL.has(type)) {
+      terminalCount += 1;
+      ended = true;
+      if (openTextId !== null) failures.push(failure("agui_text_message_open", "terminal event closed an open text message", path));
+      if (openToolId !== null) failures.push(failure("agui_tool_call_open", "terminal event closed an open tool call", path));
+      continue;
+    }
+    if (type === "TEXT_MESSAGE_START") {
+      const current = pick(event, "messageId", "message_id");
+      if (typeof current !== "string" || current.length === 0) failures.push(failure("agui_message_id_required", "TEXT_MESSAGE_START requires messageId", `${path}/messageId`));
+      if (openTextId !== null) failures.push(failure("agui_text_message_nested", "text messages cannot be nested", path));
+      openTextId = current ?? null;
+    } else if (type === "TEXT_MESSAGE_CONTENT") {
+      const current = pick(event, "messageId", "message_id");
+      if (openTextId === null || current !== openTextId) failures.push(failure("agui_text_message_not_open", "TEXT_MESSAGE_CONTENT must target an open message", path));
+    } else if (type === "TEXT_MESSAGE_END") {
+      const current = pick(event, "messageId", "message_id");
+      if (openTextId === null || current !== openTextId) failures.push(failure("agui_text_message_not_open", "TEXT_MESSAGE_END must target an open message", path));
+      openTextId = null;
+    } else if (type === "TOOL_CALL_START") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (typeof current !== "string" || current.length === 0) failures.push(failure("agui_tool_call_id_required", "TOOL_CALL_START requires toolCallId", `${path}/toolCallId`));
+      if (openToolId !== null) failures.push(failure("agui_tool_call_nested", "tool calls cannot be nested", path));
+      openToolId = current ?? null;
+    } else if (type === "TOOL_CALL_ARGS" || type === "TOOL_CALL_ARGUMENTS") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (openToolId === null || current !== openToolId) failures.push(failure("agui_tool_call_not_open", "TOOL_CALL_ARGS must target an open tool call", path));
+    } else if (type === "TOOL_CALL_END") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (openToolId === null || current !== openToolId) failures.push(failure("agui_tool_call_not_open", "TOOL_CALL_END must target an open tool call", path));
+      openToolId = null;
+    }
+  }
+  if (!started) failures.push(failure("agui_run_started_required", "sequence must contain RUN_STARTED", "events"));
+  if (terminalCount !== 1) failures.push(failure("agui_terminal_count_invalid", "sequence must contain exactly one terminal event", "events"));
+  if (terminalCount === 1 && !TERMINAL.has(eventType(events.at(-1)))) failures.push(failure("agui_terminal_not_last", "terminal event must be last", `/events/${events.length - 1}`));
+  if (openTextId !== null) failures.push(failure("agui_text_message_unclosed", "text message did not receive TEXT_MESSAGE_END", "events"));
+  if (openToolId !== null) failures.push(failure("agui_tool_call_unclosed", "tool call did not receive TOOL_CALL_END", "events"));
+  return { ok: failures.length === 0, valid: failures.length === 0, failures };
+}
+
+function protocolEvent(type, ids, fields = {}) {
+  return { type, runId: ids.runProtocolId, ...fields };
+}
+
+/** Project a domain Task/Run outcome to one deterministic AG-UI 0.0.57 stream. */
+export function projectAgUiEvents(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new AgUiProjectionError("agui_input_invalid", "projectAgUiEvents expects an object");
+  const ids = bindingIds(pick(input, "protocolBinding", "protocol_binding") ?? {}, input.task ?? {}, input.run ?? {});
+  const textValue = String(pick(input, "text", "message") ?? "");
+  const messageValue = pick(input, "messageId", "message_id") ?? `${ids.runProtocolId}:message`;
+  const tool = pick(input, "toolCall", "tool_call") ?? {};
+  const toolId = text(pick(tool, "id", "toolCallId", "tool_call_id"), `${ids.runProtocolId}:tool`);
+  const toolName = text(pick(tool, "name", "toolName", "tool_name"), "operation");
+  const toolArgs = pick(tool, "args", "arguments") ?? {};
+  const state = pick(input, "state", "snapshot") ?? {};
+  const outcome = String(pick(input, "outcome", "status") ?? pick(input.run, "state", "status") ?? pick(input.task, "state", "status") ?? "COMPLETED").toUpperCase();
+  const success = new Set(["COMPLETED", "SUCCEEDED", "SUCCESS", "OK", "PASS", "PASSED"]).has(outcome);
+  const correlation = { protocolBindingId: ids.bindingId, domainTaskId: ids.domainTaskId, domainRunId: ids.domainRunId };
+  const events = [
+    protocolEvent("RUN_STARTED", ids, { threadId: ids.threadId, input: pick(input.task, "intent", "request") ?? {}, metadata: correlation }),
+    protocolEvent("TEXT_MESSAGE_START", ids, { messageId: messageValue, role: "assistant" }),
+    protocolEvent("TEXT_MESSAGE_CONTENT", ids, { messageId: messageValue, delta: textValue }),
+    protocolEvent("TEXT_MESSAGE_END", ids, { messageId: messageValue }),
+    protocolEvent("TOOL_CALL_START", ids, { toolCallId: toolId, toolCallName: toolName }),
+    protocolEvent("TOOL_CALL_ARGS", ids, { toolCallId: toolId, delta: typeof toolArgs === "string" ? toolArgs : canonicalize(toolArgs) }),
+    protocolEvent("TOOL_CALL_END", ids, { toolCallId: toolId }),
+    protocolEvent("STATE_SNAPSHOT", ids, { snapshot: state }),
+    success
+      ? protocolEvent("RUN_FINISHED", ids, { threadId: ids.threadId, result: pick(input, "result", "output") ?? { status: outcome } })
+      : protocolEvent("RUN_ERROR", ids, { threadId: ids.threadId, message: text(pick(input, "error", "errorMessage"), outcome) }),
+  ];
+  const validation = validateAgUiTransitions(events);
+  if (!validation.ok) throw new AgUiProjectionError("agui_projection_invalid", "generated event sequence failed transition validation");
+  return cloneAndFreeze({ ok: true, events, protocolBinding: { ...correlation, protocol: "ag-ui" }, protocolIds: { threadId: ids.threadId, taskId: ids.taskProtocolId, runId: ids.runProtocolId } });
+}
+
+export const projectAGUIEvents = projectAgUiEvents;
+export const projectAguiEvents = projectAgUiEvents;
+export const createAgUiEvents = projectAgUiEvents;
+export const validateAGUITransitions = validateAgUiTransitions;
+export const assertAgUiTransitions = validateAgUiTransitions;
+export const validateEventSequence = validateAgUiTransitions;