@alexkroman1/aai-ui 6.7.2 → 6.9.1

package/dist/_upload-files.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Turning a form's `File`s into stored upload ids, pauses and all.
+ *
+ * Split out of `use-workflow-form.ts` for the 500-line cap, and the seam is a
+ * real one: that module is the two HOOKS and the state between them, where this
+ * is the walk over a submitted input — which is the only part of it that knows
+ * what a `File` is, holds a loop, and survives being re-entered.
+ *
+ * `_`-internal. `useWorkflowSubmit` is the only caller; `useWorkflowStream` sends
+ * one file rather than walking an input and shares only the gate underneath both
+ * (`_upload-session.ts`).
+ */
+import type { UploadParallel } from "@alexkroman1/aai/workflow-api";
+import { type UploadGate } from "./_upload-session.ts";
+import type { UploadStatus } from "./use-workflow-form.ts";
+import type { WorkflowApi } from "./workflow-client.ts";
+/**
+ * What one submission's uploads know about themselves, across pauses.
+ *
+ * Held by the hook rather than by the walk below, because the walk RE-RUNS: a
+ * pause unwinds nothing, so resuming re-enters `uploadFiles` with the same input
+ * and the same session, and every file whose bytes are already in is skipped by
+ * `stored` rather than sent again.
+ *
+ * Which is also why the ids live here. A resumable upload is one whose id
+ * outlives the attempt that began it — that is the whole mechanism — so an id
+ * minted per attempt would make each round a fresh upload of the whole file.
+ */
+export type UploadSession = {
+    /**
+     * What this form's remembered ids are filed under (`_upload-recall.ts`).
+     *
+     * The workflow's name, so two forms on one page do not read each other's
+     * entries. It is not a SAFETY boundary and does not need to be — a recalled id
+     * is checked against the agent before anything is sent to it — it just keeps a
+     * form from spending a round trip on another form's upload.
+     */
+    scope: string;
+    /** The id each file is being stored under, minted once. */
+    ids: Map<File, string>;
+    /** Files whose every byte has landed, by the id they landed under. */
+    stored: Map<File, string>;
+    /**
+     * Files that have had an attempt, so the next one must claim the id as its own.
+     *
+     * `sendThroughGate` tracks this itself WITHIN one file's attempts. What this
+     * carries is the attempt made by a page load that is gone: an id recalled from
+     * storage was claimed by whoever minted it, so the first attempt of this load is
+     * a resume even though this load has sent nothing.
+     */
+    tried: Set<File>;
+    /** The person's pause. */
+    gate: UploadGate;
+};
+/** A fresh session for one submission of `workflow`. */
+export declare function createUploadSession(workflow: string): UploadSession;
+/**
+ * Replace every `File` in a submitted form with the id of a stored upload,
+ * reporting how far each one has got.
+ *
+ * Sequential rather than `Promise.all`: these are large bodies, and a form with
+ * two 200 MB recordings should send them one after another rather than compete
+ * for the same connection. That is also what makes a single bar honest — one
+ * file is in flight at a time, and `index`/`count` say which.
+ *
+ * Anything that is not a `File` (or an array of them) passes through untouched,
+ * so this is invisible to every form that has none — including one whose values
+ * are not an object at all, which `submit` accepts.
+ *
+ * ## `uploadStream`, not `upload`, and the id is the reason
+ *
+ * The difference between the two calls is only who mints the id — and that is
+ * exactly what decides whether an interrupted upload can be picked up again. An
+ * `upload` mints its own at the END and hands it back, so a caller whose upload
+ * died has nothing to name what was stored and no choice but to send the file
+ * again. A `uploadStream` is told the id up front, so the windows already in the
+ * store are addressable, which is what both a pause and a server restart need.
+ *
+ * Nothing else about the submission changes: the run is still started after the
+ * last byte lands, so the incomplete record a streamed upload leaves along the
+ * way is one nobody reads.
+ */
+export declare function uploadFiles(api: WorkflowApi, input: unknown, report: (status: UploadStatus) => void, parallel: UploadParallel | undefined, session: UploadSession): Promise<unknown>;

package/dist/_upload-recall.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where an upload's ID survives a page RELOAD.
+ *
+ * A streamed upload is resumable because its id outlives the attempt that began
+ * it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
+ * pause a person can press. Both of them hold the id in MEMORY: the walk's
+ * `UploadSession` lives in a `useRef`, so a reload was the one interruption the
+ * mechanism could not survive. Everything else was already in place — the windows
+ * were still in the store, the agent could still name them
+ * (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
+ * had thrown away the only name for them. So a person who refreshed at 90% of a
+ * 200 MB recording sent the whole file again, which is the one interruption they
+ * are most likely to cause on purpose.
+ *
+ * This is that name, written down. It is what tus-js-client's `urlStorage` and
+ * Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
+ * uses for a session id.
+ *
+ * ## A FINGERPRINT, because a `File` has no name a page can address
+ *
+ * A file from a picker carries no path and no handle, so the key is what
+ * tus-js-client fingerprints on: size, last-modified, type and name. Two
+ * different files agreeing on all four is the case this cannot tell apart — and
+ * the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
+ * what the id actually holds before sending a byte to it, so a wrong hit costs
+ * one `GET` and a fresh id rather than a corrupted upload.
+ *
+ * ## `sessionStorage`, deliberately
+ *
+ * The same call `session-resume-store.ts` makes, for a reason that happens to be
+ * stronger here: a reload and a same-tab navigation are exactly what this is for,
+ * and an id from yesterday names an upload the agent's sweep has very likely
+ * already collected. A tab is also the boundary the walk itself has — two tabs
+ * uploading the same recording are two submissions.
+ *
+ * Every access is guarded. Storage throws outright in Safari private mode and
+ * under a blocking policy, and an upload that cannot be REMEMBERED must degrade
+ * to the upload we would have done anyway rather than failing to start.
+ */
+/**
+ * The id this file was last being stored under in this tab, if any.
+ *
+ * A hit is a CANDIDATE and never a decision — see the module doc.
+ *
+ * @internal
+ */
+export declare function recallUploadId(scope: string, file: File): string | undefined;
+/**
+ * Remember the id this file is being stored under.
+ *
+ * Called before the first byte leaves rather than after the last one lands: the
+ * reload this exists for happens in between, and an id written at the end is an
+ * id written for the one case that did not need it.
+ *
+ * @internal
+ */
+export declare function rememberUploadId(scope: string, file: File, id: string): void;
+/**
+ * Forget it: the agent holds nothing resumable under this id.
+ *
+ * The other half of the agent deciding. Without it a swept upload is re-read on
+ * every submission of the same file for the life of the tab, which is a round
+ * trip spent learning the same 404.
+ *
+ * @internal
+ */
+export declare function forgetUploadId(scope: string, file: File): void;

package/dist/_upload-session.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Driving ONE resumable upload from a page: its id, and the gate a person can
+ * close.
+ *
+ * The SDK already survives the server going away — a round that fails for a
+ * reason that looks like an outage re-enters itself with `resume: true` and sends
+ * only the windows that are missing (`aai/sdk/_upload-resume.ts`). This is the
+ * same mechanism turned around and handed to the PERSON: pausing is an outage
+ * they caused, resuming is the round after it, and the store cannot tell the two
+ * apart because there is nothing to tell apart.
+ *
+ * ## Why a gate rather than a boolean
+ *
+ * Pausing has to do two things that a `paused` flag cannot: stop the bytes that
+ * are already on the wire, and hold the loop that would send the next ones. So it
+ * is an `AbortController` and a promise — abort what is in flight, and park the
+ * uploader on `settle()` until somebody opens the gate again.
+ *
+ * The controller is REPLACED on resume rather than reused, because an aborted
+ * signal stays aborted; a caller therefore has to read {@link UploadGate.signal}
+ * fresh for each attempt rather than capturing it once.
+ *
+ * ## The loop this is built for
+ *
+ * ```ts no-check
+ * while (!gate.cancelled) {
+ *   await gate.settle();
+ *   if (gate.cancelled) break;
+ *   try {
+ *     await api.uploadStream(id, file, { signal: gate.signal, resume: tried });
+ *     break;
+ *   } catch (err) {
+ *     // An abort that is not a cancel is a PAUSE: go back and wait.
+ *     if (!isAbort(err) || gate.cancelled) throw err;
+ *   }
+ * }
+ * ```
+ *
+ * **The catch keys off the abort, not off `gate.paused`,** and that is the one
+ * subtle part. Pausing and immediately resuming — a double-click, or a person
+ * changing their mind inside the round trip — resolves the gate before the
+ * rejection this abort caused has even landed, so a `paused` check would read
+ * `false` and rethrow an `AbortError` as though the upload had failed. Every
+ * abort reaching that catch was caused by this gate, so every one of them is a
+ * pause unless the gate was cancelled outright.
+ */
+/** A person's pause, as the uploader sees it. */
+export type UploadGate = {
+    /** Whether the gate is currently closed. For rendering, not for control flow. */
+    readonly paused: boolean;
+    /** Whether the upload was abandoned. A cancelled gate never opens again. */
+    readonly cancelled: boolean;
+    /**
+     * The signal for the NEXT attempt. Re-read it per attempt: resuming installs a
+     * fresh controller, and the previous one stays aborted forever.
+     */
+    readonly signal: AbortSignal;
+    /** Stop the bytes in flight and hold the uploader. A no-op when already closed. */
+    pause: () => void;
+    /** Open the gate and install a fresh signal. A no-op when not paused. */
+    resume: () => void;
+    /**
+     * Abandon the upload for good.
+     *
+     * Distinct from a pause in exactly one way that matters to the loop above: it
+     * releases the gate rather than holding it, so an uploader parked on `settle()`
+     * wakes up and leaves instead of waiting for a resume that is not coming. What
+     * a caller does with a cancelled upload's stored windows is its own business —
+     * they stay in the store, addressable by an id only the caller has.
+     */
+    cancel: () => void;
+    /** Resolves as soon as the gate is open — immediately, when it already is. */
+    settle: () => Promise<void>;
+};
+/** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
+export declare function isAbortError(err: unknown): boolean;
+/** A fresh upload id: a capability, so it is random rather than derived. */
+export declare function randomUploadId(): string;
+/**
+ * Send one file, waiting out however many pauses the person takes.
+ *
+ * The loop from the module doc, written once: both hooks need exactly this and a
+ * second copy of it is a second place for the abort/pause distinction to be got
+ * wrong. `send` is handed whether this attempt must CLAIM the id as its own —
+ * false the first time, since a fresh id has nothing to resume and saying
+ * otherwise waives the refusal that makes a caller-chosen id safe.
+ *
+ * Throws whatever `send` threw, except an abort the gate caused. A cancelled gate
+ * throws too: the caller distinguishes it by reading `gate.cancelled`, which is
+ * how an abandoned submission unwinds without being reported as a failure.
+ */
+export declare function sendThroughGate(gate: UploadGate, send: (resume: boolean) => Promise<void>): Promise<void>;
+/**
+ * A gate, open.
+ *
+ * One per upload rather than one per hook: the id and the windows already stored
+ * belong to a file, so a gate that outlived its file would resume something else.
+ */
+export declare function createUploadGate(): UploadGate;

package/dist/components/upload-progress.d.ts

@@ -22,6 +22,14 @@ import type { UploadStatus } from "../use-workflow-form.ts";
  * - **The file is NAMED, and counted when there is more than one.** Files are
  *   sent one after another, so a single bar otherwise appears to restart from
  *   zero partway through with nothing to say why.
+ * - **A paused upload SAYS SO, rather than being a bar that stopped.** Those look
+ *   identical, which is the whole reason `UploadStatus.paused` exists, and the
+ *   fill stops animating so the difference is visible without reading.
+ *
+ * The pause control appears only when a handler for it is passed. That is not
+ * politeness about props: a button whose press does nothing is worse than no
+ * button, and a page holding an `upload` it did not produce (a saved status, a
+ * parent's state) has nothing to pause.
  *
  * @example
  * ```tsx
@@ -41,12 +49,17 @@ import type { UploadStatus } from "../use-workflow-form.ts";
  *
  * @param upload - What `useWorkflowSubmit` reports. `undefined` renders nothing,
  *   so a page may pass its state straight through.
+ * @param onPause - The hook's `pauseUpload`. Pass it together with `onResume` to
+ *   get the control; pass neither for a bar that only reports.
+ * @param onResume - The hook's `resumeUpload`.
  * @param className - Replaces the default classes rather than extending them,
  *   so a custom chrome is not fighting a default it did not ask for.
  *
  * @public
  */
-export declare function UploadProgressBar({ upload, className, }: {
+export declare function UploadProgressBar({ upload, onPause, onResume, className, }: {
     upload?: UploadStatus | undefined;
+    onPause?: (() => void) | undefined;
+    onResume?: (() => void) | undefined;
     className?: string | undefined;
 }): ReactNode;

package/dist/default-client/assets/index-DTLrhtTF.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-rotate-x:initial;--tw-rotate-y:initial;--tw-rotate-z:initial;--tw-skew-x:initial;--tw-skew-y:initial;--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial;--tw-ordinal:initial;--tw-slashed-zero:initial;--tw-numeric-figure:initial;--tw-numeric-spacing:initial;--tw-numeric-fraction:initial;--tw-shadow:0 0 #0000;--tw-shadow-color:initial;--tw-shadow-alpha:100%;--tw-inset-shadow:0 0 #0000;--tw-inset-shadow-color:initial;--tw-inset-shadow-alpha:100%;--tw-ring-color:initial;--tw-ring-shadow:0 0 #0000;--tw-inset-ring-color:initial;--tw-inset-ring-shadow:0 0 #0000;--tw-ring-inset:initial;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-offset-shadow:0 0 #0000;--tw-outline-style:solid;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}@layer theme{:root,:host{--font-sans:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--font-weight-normal:400;--font-weight-medium:500;--font-weight-semibold:600;--tracking-wide:.025em;--radius-sm:.25rem;--radius-md:.375rem;--radius-lg:.5rem;--radius-xl:.75rem;--ease-out:cubic-bezier(0, 0, .2, 1);--ease-in-out:cubic-bezier(.4, 0, .2, 1);--animate-pulse:pulse 2s cubic-bezier(.4, 0, .6, 1) infinite;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono);--font-aai:"Monument Grotesk", "ABC Monument Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif;--font-aai-serif:"Source Serif 4", "Source Serif Pro", Charter, "Iowan Old Style", Georgia, serif;--font-aai-mono:"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;--radius-aai:4px}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring:where(:not(iframe)){outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}html,body{margin:0;padding:0}}@layer components;@layer utilities{.collapse{visibility:collapse}.invisible{visibility:hidden}.visible{visibility:visible}.absolute{position:absolute}.fixed{position:fixed}.relative{position:relative}.static{position:static}.order-last{order:9999}.container{width:100%}@media (width>=40rem){.container{max-width:40rem}}@media (width>=48rem){.container{max-width:48rem}}@media (width>=64rem){.container{max-width:64rem}}@media (width>=80rem){.container{max-width:80rem}}@media (width>=96rem){.container{max-width:96rem}}.m-0{margin:0}.mx-auto{margin-inline:auto}.my-0\.5{margin-block:calc(var(--spacing) * .5)}.my-1\.5{margin-block:calc(var(--spacing) * 1.5)}.my-2\.5{margin-block:calc(var(--spacing) * 2.5)}.mt-2{margin-top:calc(var(--spacing) * 2)}.mt-3{margin-top:calc(var(--spacing) * 3)}.mb-1\.5{margin-bottom:calc(var(--spacing) * 1.5)}.box-border{box-sizing:border-box}.block{display:block}.contents{display:contents}.flex{display:flex}.grid{display:grid}.inline{display:inline}.inline-flex{display:inline-flex}.table{display:table}.h-1\.5{height:calc(var(--spacing) * 1.5)}.h-4{height:calc(var(--spacing) * 4)}.h-6{height:calc(var(--spacing) * 6)}.h-9{height:calc(var(--spacing) * 9)}.h-11{height:calc(var(--spacing) * 11)}.h-\[7px\]{height:7px}.h-full{height:100%}.h-screen{height:100vh}.max-h-64{max-height:calc(var(--spacing) * 64)}.max-h-\[40vh\]{max-height:40vh}.min-h-0{min-height:0}.min-h-5{min-height:calc(var(--spacing) * 5)}.min-h-screen{min-height:100vh}.w-1\.5{width:calc(var(--spacing) * 1.5)}.w-4{width:calc(var(--spacing) * 4)}.w-\[7px\]{width:7px}.w-fit{width:fit-content}.w-full{width:100%}.max-w-75{max-width:calc(var(--spacing) * 75)}.max-w-105{max-width:calc(var(--spacing) * 105)}.max-w-190{max-width:calc(var(--spacing) * 190)}.max-w-\[82\%\]{max-width:82%}.max-w-\[min\(78\%\,64ch\)\]{max-width:min(78%,64ch)}.min-w-0{min-width:0}.flex-1{flex:1}.shrink{flex-shrink:1}.shrink-0{flex-shrink:0}.grow{flex-grow:1}.basis-full{flex-basis:100%}.border-collapse{border-collapse:collapse}.rotate-90{rotate:90deg}.transform{transform:var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,)}.animate-pulse{animation:var(--animate-pulse)}.cursor-pointer{cursor:pointer}.resize{resize:both}.\[scrollbar-width\:none\]{scrollbar-width:none}.list-decimal{list-style-type:decimal}.list-disc{list-style-type:disc}.appearance-none{appearance:none}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.items-baseline{align-items:baseline}.items-center{align-items:center}.items-end{align-items:flex-end}.justify-between{justify-content:space-between}.justify-center{justify-content:center}.justify-end{justify-content:flex-end}.gap-1{gap:var(--spacing)}.gap-1\.5{gap:calc(var(--spacing) * 1.5)}.gap-2{gap:calc(var(--spacing) * 2)}.gap-2\.5{gap:calc(var(--spacing) * 2.5)}.gap-3{gap:calc(var(--spacing) * 3)}.gap-4{gap:calc(var(--spacing) * 4)}.gap-5{gap:calc(var(--spacing) * 5)}.truncate{text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.overflow-auto{overflow:auto}.overflow-hidden{overflow:hidden}.overflow-x-auto{overflow-x:auto}.overflow-y-auto{overflow-y:auto}.rounded-aai{border-radius:var(--radius-aai)}.rounded-full{border-radius:2147483647px}.rounded-lg{border-radius:var(--radius-lg)}.rounded-md{border-radius:var(--radius-md)}.rounded-sm{border-radius:var(--radius-sm)}.rounded-xl{border-radius:var(--radius-xl)}.border{border-style:var(--tw-border-style);border-width:1px}.border-t{border-top-style:var(--tw-border-style);border-top-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-l{border-left-style:var(--tw-border-style);border-left-width:1px}.border-l-2{border-left-style:var(--tw-border-style);border-left-width:2px}.border-none{--tw-border-style:none;border-style:none}.border-\(--aai-btn-bd\){border-color:var(--aai-btn-bd)}.bg-\(--aai-btn-bg\){background-color:var(--aai-btn-bg)}.bg-transparent{background-color:#0000}.p-2\.5{padding:calc(var(--spacing) * 2.5)}.p-4{padding:calc(var(--spacing) * 4)}.p-7{padding:calc(var(--spacing) * 7)}.p-8{padding:calc(var(--spacing) * 8)}.px-1{padding-inline:var(--spacing)}.px-2{padding-inline:calc(var(--spacing) * 2)}.px-3{padding-inline:calc(var(--spacing) * 3)}.px-3\.5{padding-inline:calc(var(--spacing) * 3.5)}.px-5{padding-inline:calc(var(--spacing) * 5)}.px-6{padding-inline:calc(var(--spacing) * 6)}.px-7{padding-inline:calc(var(--spacing) * 7)}.px-10{padding-inline:calc(var(--spacing) * 10)}.py-0\.5{padding-block:calc(var(--spacing) * .5)}.py-1{padding-block:var(--spacing)}.py-1\.5{padding-block:calc(var(--spacing) * 1.5)}.py-2{padding-block:calc(var(--spacing) * 2)}.py-2\.5{padding-block:calc(var(--spacing) * 2.5)}.py-3{padding-block:calc(var(--spacing) * 3)}.py-8{padding-block:calc(var(--spacing) * 8)}.py-12{padding-block:calc(var(--spacing) * 12)}.pl-1\.5{padding-left:calc(var(--spacing) * 1.5)}.pl-3{padding-left:calc(var(--spacing) * 3)}.pl-4{padding-left:calc(var(--spacing) * 4)}.pl-5{padding-left:calc(var(--spacing) * 5)}.text-center{text-align:center}.text-left{text-align:left}.font-aai{font-family:var(--font-aai)}.font-aai-mono{font-family:var(--font-aai-mono)}.font-aai-serif{font-family:var(--font-aai-serif)}.font-mono{font-family:var(--font-mono)}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.text-\[0\.625rem\]{font-size:.625rem}.text-\[9px\]{font-size:9px}.text-\[10px\]{font-size:10px}.text-\[11px\]{font-size:11px}.text-\[12\.5px\]{font-size:12.5px}.text-\[12px\]{font-size:12px}.text-\[13px\]{font-size:13px}.text-\[14px\]{font-size:14px}.text-\[15px\]{font-size:15px}.text-\[16px\]{font-size:16px}.text-\[17px\]{font-size:17px}.text-\[22px\]{font-size:22px}.text-\[32px\]{font-size:32px}.leading-4{--tw-leading:calc(var(--spacing) * 4);line-height:calc(var(--spacing) * 4)}.leading-\[1\.2\]{--tw-leading:1.2;line-height:1.2}.leading-\[1\.15\]{--tw-leading:1.15;line-height:1.15}.leading-\[22px\]{--tw-leading:22px;line-height:22px}.leading-\[23px\]{--tw-leading:23px;line-height:23px}.leading-\[130\%\]{--tw-leading:130%;line-height:130%}.leading-none{--tw-leading:1;line-height:1}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-normal{--tw-font-weight:var(--font-weight-normal);font-weight:var(--font-weight-normal)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-\[-0\.2px\]{--tw-tracking:-.2px;letter-spacing:-.2px}.tracking-\[1\.2px\]{--tw-tracking:1.2px;letter-spacing:1.2px}.tracking-\[1\.4px\]{--tw-tracking:1.4px;letter-spacing:1.4px}.tracking-wide{--tw-tracking:var(--tracking-wide);letter-spacing:var(--tracking-wide)}.text-balance{text-wrap:balance}.wrap-break-word{overflow-wrap:break-word}.whitespace-nowrap{white-space:nowrap}.whitespace-pre-wrap{white-space:pre-wrap}.text-\(--aai-btn-fg\){color:var(--aai-btn-fg)}.uppercase{text-transform:uppercase}.italic{font-style:italic}.tabular-nums{--tw-numeric-spacing:tabular-nums;font-variant-numeric:var(--tw-ordinal,) var(--tw-slashed-zero,) var(--tw-numeric-figure,) var(--tw-numeric-spacing,) var(--tw-numeric-fraction,)}.underline{text-decoration-line:underline}.underline-offset-2{text-underline-offset:2px}.opacity-60{opacity:.6}.opacity-70{opacity:.7}.ring{--tw-ring-shadow:var(--tw-ring-inset,) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color,currentcolor);box-shadow:var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow)}.outline{outline-style:var(--tw-outline-style);outline-width:1px}.filter{filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to,opacity,box-shadow,transform,translate,scale,rotate,filter,-webkit-backdrop-filter,backdrop-filter,display,content-visibility,overlay,pointer-events;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-\[width\]{transition-property:width;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-150{--tw-duration:.15s;transition-duration:.15s}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.ease-out{--tw-ease:var(--ease-out);transition-timing-function:var(--ease-out)}.outline-none{--tw-outline-style:none;outline-style:none}.select-none{-webkit-user-select:none;user-select:none}.file\:mr-3::file-selector-button{margin-right:calc(var(--spacing) * 3)}.file\:cursor-pointer::file-selector-button{cursor:pointer}.file\:rounded-aai::file-selector-button{border-radius:var(--radius-aai)}.file\:border-0::file-selector-button{border-style:var(--tw-border-style);border-width:0}.file\:px-3::file-selector-button{padding-inline:calc(var(--spacing) * 3)}.file\:py-1\.5::file-selector-button{padding-block:calc(var(--spacing) * 1.5)}.file\:font-aai::file-selector-button{font-family:var(--font-aai)}.file\:text-sm::file-selector-button{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.file\:font-medium::file-selector-button{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.file\:\[color\:var\(--aai-file-button-fg\)\]::file-selector-button{color:var(--aai-file-button-fg)}.file\:\[background\:var\(--aai-file-button-bg\)\]::file-selector-button{background:var(--aai-file-button-bg)}.first\:mt-0:first-child{margin-top:0}.last\:mb-0:last-child{margin-bottom:0}.focus-visible\:\[outline\:2px_solid\]:focus-visible{outline:2px solid}.focus-visible\:\[outline-offset\:2px\]:focus-visible{outline-offset:2px}@media (hover:hover){.enabled\:hover\:border-\(--aai-btn-bd-hover\):enabled:hover{border-color:var(--aai-btn-bd-hover)}.enabled\:hover\:bg-\(--aai-btn-bg-hover\):enabled:hover{background-color:var(--aai-btn-bg-hover)}.enabled\:hover\:text-\(--aai-btn-fg-hover\):enabled:hover{color:var(--aai-btn-fg-hover)}}.disabled\:cursor-not-allowed:disabled{cursor:not-allowed}.disabled\:opacity-50:disabled{opacity:.5}@media (width>=40rem){.sm\:ml-auto{margin-left:auto}.sm\:max-w-\[60\%\]{max-width:60%}.sm\:basis-auto{flex-basis:auto}.sm\:px-16{padding-inline:calc(var(--spacing) * 16)}.sm\:py-14{padding-block:calc(var(--spacing) * 14)}}@media (width>=48rem){.md\:order-none{order:0}.md\:h-screen{height:100vh}.md\:max-h-none{max-height:none}.md\:w-\(--aai-sidebar-w\){width:var(--aai-sidebar-w)}.md\:flex-row{flex-direction:row}.md\:border-t-0{border-top-style:var(--tw-border-style);border-top-width:0}.md\:border-r{border-right-style:var(--tw-border-style);border-right-width:1px}.md\:border-b-0{border-bottom-style:var(--tw-border-style);border-bottom-width:0}.md\:border-l{border-left-style:var(--tw-border-style);border-left-width:1px}}}@keyframes aai-pulse{0%,to{opacity:1;transform:scale(1)}50%{opacity:.45;transform:scale(.82)}}@keyframes aai-bounce{0%,80%,to{opacity:.3;transform:scale(.8)}40%{opacity:1;transform:scale(1)}}@keyframes aai-shimmer{0%{background-position:-200% 0}to{background-position:200% 0}}.tool-shimmer{-webkit-text-fill-color:transparent;background:linear-gradient(90deg,currentColor 25%,#0000 50%,currentColor 75%) 0 0/200% 100%;-webkit-background-clip:text;background-clip:text;animation:2s infinite aai-shimmer}@property --tw-rotate-x{syntax:"*";inherits:false}@property --tw-rotate-y{syntax:"*";inherits:false}@property --tw-rotate-z{syntax:"*";inherits:false}@property --tw-skew-x{syntax:"*";inherits:false}@property --tw-skew-y{syntax:"*";inherits:false}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@property --tw-ordinal{syntax:"*";inherits:false}@property --tw-slashed-zero{syntax:"*";inherits:false}@property --tw-numeric-figure{syntax:"*";inherits:false}@property --tw-numeric-spacing{syntax:"*";inherits:false}@property --tw-numeric-fraction{syntax:"*";inherits:false}@property --tw-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-shadow-color{syntax:"*";inherits:false}@property --tw-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-inset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-shadow-color{syntax:"*";inherits:false}@property --tw-inset-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-ring-color{syntax:"*";inherits:false}@property --tw-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-ring-color{syntax:"*";inherits:false}@property --tw-inset-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-ring-inset{syntax:"*";inherits:false}@property --tw-ring-offset-width{syntax:"<length>";inherits:false;initial-value:0}@property --tw-ring-offset-color{syntax:"*";inherits:false;initial-value:#fff}@property --tw-ring-offset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-outline-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}@keyframes pulse{50%{opacity:.5}}

package/dist/default-client/index.html

@@ -6,9 +6,9 @@
     <title>aai</title>
     <link rel="icon" href="./favicon.ico" />
     <style>html, body { background: #FBF8F2; margin: 0; }</style>
-    <script type="module" crossorigin src="./assets/index-CepvxbNU.js"></script>
+    <script type="module" crossorigin src="./assets/index-DXODx_9r.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/client-audio-constants-Ck0IJO4c.js">
-    <link rel="stylesheet" crossorigin href="./assets/index-BZlePk3y.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-DTLrhtTF.css">
   </head>
   <body>
     <main id="app"></main>

package/dist/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { DefaultToolResult } from "@alexkroman1/aai";
+import type { DefaultToolResult, StateProjection } from "@alexkroman1/aai";
 import type { ToolCallInfo } from "./types.ts";
 /**
  * Fire a callback when a tool call settles, with the tool's JSON result.
@@ -39,6 +39,42 @@ export declare function useToolResult<R = DefaultToolResult>(callback: (name: st
  * @public
  */
 export declare function useAgentState<S = DefaultToolResult>(): S | null;
+/**
+ * The agent's projected session state, typed and defaulted by the SAME
+ * projection the agent pushes — pass `slot.projection(view)` and there is no
+ * type argument to restate and no empty frame to derive.
+ *
+ * This is the overload to reach for whenever `syncState` is a slot projection,
+ * because it closes the round-trip the other two leave open. A projection is
+ * callable, so the pre-first-push frame is what `projection()` returns — the
+ * `fallback` overload's own doc tells you to build it that way — and the
+ * projection's return type is the state's type, so `useAgentState<CartView>`
+ * was restating what `cartView` already knew. Both halves came out of the same
+ * declaration and both were written by hand:
+ *
+ * ```tsx no-check
+ * // `no-check`: the projection lives with the agent, in another file.
+ * // Before — the empty frame derived by hand, the type named three times:
+ * const EMPTY: CartView = cartSlot.projection(cartView)(undefined);
+ * const cart = useAgentState<CartView>(EMPTY);
+ *
+ * // After — `shared.ts` exports the projection once, both ends import it:
+ * const cart = useAgentState(cartProjection);
+ * ```
+ *
+ * The empty frame is memoized on the projection's identity, so a module-scope
+ * projection (the normal case) produces ONE frame for the life of the
+ * component — which the `fallback` overload can only ask you to arrange by
+ * hoisting, and which a `slot.projection(view)` spelled inline in the render
+ * body silently got wrong.
+ *
+ * @param projection - The same `slot.projection(view)` the agent declares as
+ *   `syncState`. Export it from the module that declares the slot so the two
+ *   ends cannot drift.
+ *
+ * @public
+ */
+export declare function useAgentState<V>(projection: StateProjection<V>): V;
 /**
  * The agent's projected session state, falling back to `fallback` before the
  * first push — so the return is never `null` and a sidebar needs no branch for

package/dist/hooks.js

@@ -1,6 +1,6 @@
 import { useSessionSelector } from "./context.js";
 import { i as tryParseJSON } from "./_utils-B6498_bm.js";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 //#region hooks.ts
 /** Index of the first item whose sequence number is above the watermark (tail scan from the end). */
 function tailStart(items, seqOf, watermark) {
@@ -80,7 +80,10 @@ function useToolResult(...args) {
 }
 function useAgentState(fallback) {
 	const state = useSessionSelector((snapshot) => snapshot.agentState);
+	const isProjection = typeof fallback === "function";
+	const projected = useMemo(() => isProjection ? fallback() : void 0, [fallback, isProjection]);
 	if (state !== null) return state;
+	if (isProjection) return projected;
 	return fallback === void 0 ? null : fallback;
 }
 /**