@alexkroman1/aai-ui 0.17.0 → 0.18.0

package/dist/workflow-submission.d.ts

@@ -0,0 +1,265 @@
+/**
+ * What a workflow SUBMISSION is, as a type: the object `useWorkflowSubmit` and
+ * `useWorkflowStream` both hand back. Moved out of `use-workflow-form.ts` at
+ * the source-length cap, on the seam `form-types.ts` is cut on — the two hooks
+ * and the form statechart all name these, and a type living in one of them
+ * would make the others import a hook to say what they return.
+ */
+import type { UploadProgress, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { FormValues } from "./components/form-types.ts";
+import type { WorkflowRun } from "./workflow-client.ts";
+import type { SubmitInputOf } from "./workflow-def-types.ts";
+/**
+ * What {@link WorkflowSubmission.upload} reports while the bytes are going.
+ *
+ * The SDK's per-request {@link UploadProgress} plus WHICH file it describes,
+ * because a form is allowed more than one and a bar over "the upload" would
+ * restart at zero partway through with nothing to say why.
+ *
+ * @sealed
+ * @public
+ */
+export type UploadStatus = UploadProgress & {
+    /** The file being sent, by the name the picker gave it. */
+    name: string;
+    /** Which file of the submission this is, counting from 1. */
+    index: number;
+    /** How many files this submission sends in total. */
+    count: number;
+    /**
+     * Whether the person has parked this upload.
+     *
+     * A paused upload is not a stopped one: the windows already stored stay stored,
+     * `loaded` holds where it got to, and resuming sends what is missing rather than
+     * the file. So a bar rendering this reads "Paused at 62%", never "62% and
+     * frozen" — which is what a page could otherwise only guess from a number that
+     * stopped moving, the same ambiguity `complete` exists to remove on the run side.
+     */
+    paused: boolean;
+};
+/**
+ * The two marks a submission's wall clock is read from — press to settle,
+ * across the upload, the run, and the gap between them, which no server-side
+ * number can give: `output.elapsedMs` is the RUN's own clock and begins after
+ * the upload. Only the browser holds both ends.
+ *
+ * `performance.now()` marks rather than elapsed durations, and that is the
+ * load-bearing part: an elapsed number is stale the instant it is computed, so
+ * a page holding one has to re-render to keep it true. A mark lets the one
+ * section that prints a running clock re-render on its own interval and read
+ * `performance.now() - submittedAt` at render. Monotonic, so a clock
+ * correction cannot make a run look instant, or negative.
+ *
+ * @sealed
+ * @public
+ */
+export type WorkflowSubmissionTiming = {
+    /** When `submit()` was called on this mount, or `undefined` before the first. */
+    submittedAt?: number | undefined;
+    /**
+     * When the submission settled — the run reached a terminal status, or the
+     * submit itself failed — measured at that moment rather than at the next
+     * render. `undefined` while it is in flight, and for a run this page did
+     * not start (there was no press to time from).
+     */
+    settledAt?: number | undefined;
+};
+/**
+ * Who can find the run again — the lifetime of the key it was recorded under.
+ *
+ * - `"tab"` — `useWorkflowSubmit`'s own `sessionStorage` key: a reload or a
+ *   same-tab navigation finds the run; a new tab does not.
+ * - `"browser"` — a `localStorage` key (`key: { storage: "local" }`, or
+ *   `useRunKey({ storage: "local" })`), or a key the page supplied itself (an
+ *   account's id): any tab on this browser finds it, so closing the tab loses
+ *   nothing.
+ * - `"none"` — nothing will find it: `recover: false`, or `useWorkflowStream`,
+ *   whose run is reading the bytes THIS page is sending and is ended, not
+ *   orphaned, by a reload.
+ *
+ * `<WorkflowPendingNote>` reads it to say the right sentence; the raw fact is
+ * published so a page with its own note can too.
+ *
+ * @public
+ */
+export type WorkflowSubmissionScope = "tab" | "browser" | "none";
+/**
+ * What {@link useWorkflowSubmit} returns.
+ *
+ * @see {@link WorkflowStreamSubmission} — an ALIAS of this type, returned by
+ * `useWorkflowStream`, which is a drop-in sibling. Exactly two fields MEAN
+ * something different there, and both differences follow from WHEN the run is
+ * created: there, `submit()` resolves when the UPLOAD finishes rather than when
+ * the run is accepted, and `run` is non-`undefined` from before the bytes are
+ * in, so a page can render `<WorkflowProgress>` beside the upload bar instead
+ * of after it. Here the run does not exist until the last byte lands.
+ *
+ * @sealed
+ */
+export type WorkflowSubmission<R = unknown, I = unknown> = {
+    /**
+     * Start a run with this input. Resolves once the run EXISTS — progress
+     * arrives through `run` — so a `<Form>`'s handler can await it to know the
+     * submission was accepted.
+     */
+    submit: (input: I) => Promise<void>;
+    /**
+     * Start a run from a `<Form>`'s values, which are UNVALIDATED.
+     *
+     * The same function as {@link WorkflowSubmission.submit}, with the type the
+     * form path can honestly offer. `FormValues` is `Record<string, unknown>`
+     * scraped off the DOM at submit time — a `<TextField name="limit">`
+     * contributes a string whatever the schema says — so the shape is not known
+     * here and the SERVER is what checks it against the workflow's schema.
+     *
+     * Two doors rather than one loose one: `submit` takes the workflow's own
+     * input type, so a hand-built object is checked at compile time and
+     * `submit({ ur1: 42 })` is an error; widening it to accept `FormValues` would
+     * have made every object satisfy it and given the typing back. Reaching for
+     * this one is the author saying "these came from a form", which is a fact
+     * about the values and not a cast.
+     */
+    submitForm: (values: FormValues) => Promise<void>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /**
+     * End the current run's `sleep()` early — "file it now" — resolving how many
+     * pending sleeps were interrupted.
+     *
+     * Bound to the run this submission is following, which is the point: it is
+     * the only reason a page holding one of these hooks needed an `api` of its
+     * own. `0` is an answer rather than a failure (the run had already moved past
+     * its wait, or there is no run yet), so nothing here has to be guarded.
+     */
+    wake: () => Promise<number>;
+    /**
+     * Stop the current run, resolving whether this call is what ended it.
+     *
+     * `false` for a run that had already finished, and for no run at all — the
+     * SDK's contract, because two tabs pressing Stop is ordinary. Distinct from
+     * `reset()`, which puts the FORM back and leaves the run running.
+     */
+    cancel: () => Promise<boolean>;
+    /** The run, once started, followed to completion. */
+    run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` on this mount until `reset()` — did THIS page start
+     * the run it is showing?
+     *
+     * A page needs it to say the right sentence and cannot derive it: a run
+     * ADOPTED by the mount-time lookup after a reload looks exactly like one this
+     * page started. Six templates kept a `useState(false)` next to this hook, set
+     * it in their `onSubmit` and mirrored it in their `onClear` — shadow state
+     * for a fact only this hook can know, since it is the thing that decides
+     * between `submit()` and the recovery lookup. One of the six grew a fourth
+     * branch and had to move the whole note into its own module with its own
+     * spec, which is what a seam missing one layer down looks like.
+     *
+     * The RAW fact rather than a derived "recovered", deliberately: with `run`
+     * these are three states, not two, and the third is the one a page most needs
+     * to explain. `startedHere` is "you pressed the button"; `!startedHere &&
+     * !run` is the mount-time lookup still going; `!startedHere && run` is a run
+     * this browser started earlier, now in front of somebody who did not press
+     * anything. A boolean meaning only the last of those cannot express the
+     * middle one.
+     *
+     * @example
+     * ```ts
+     * declare const submission: import("@alexkroman1/aai-ui").WorkflowSubmission;
+     * const note = submission.startedHere
+     *   ? "You can close this tab or reload it — this page will find the run again."
+     *   : submission.run === undefined
+     *     ? "Looking for a run this tab started earlier…"
+     *     : "Still working on the run this tab started earlier. Reloading is safe.";
+     * ```
+     */
+    startedHere: boolean;
+    /**
+     * True from `submit()` until the run reaches a terminal status.
+     *
+     * The WORK, not the request: a run outlives its `POST`, and a submit button
+     * that re-enabled on the response would invite a second submission of work
+     * already in flight.
+     */
+    pending: boolean;
+    /**
+     * How far the submission's files have got, while any are still going.
+     *
+     * Undefined before the first byte and again from the moment the last one
+     * lands, so a page can render `{upload && <UploadProgressBar upload={upload} />}`
+     * and the bar exists exactly for as long as there is an upload to describe. A
+     * form with no files never sets it at all.
+     *
+     * The wait it covers is the one `run` cannot: a run does not EXIST until its
+     * input is stored, so `pending` is true and there is nothing to poll — which
+     * for a 200 MB recording is minutes of a page that looks stuck.
+     */
+    upload: UploadStatus | undefined;
+    /**
+     * Park the upload where it is, stopping the bytes in flight.
+     *
+     * The windows already stored stay stored, so `resumeUpload()` sends what is
+     * missing rather than the file — which is the difference between a pause a
+     * person will actually use on a 200 MB recording and a cancel dressed up as one.
+     *
+     * `submit()`'s promise stays unresolved across a pause, because the submission
+     * genuinely has not finished: the run does not exist until the last byte lands,
+     * so resolving here would tell a `<Form>` the work was accepted when nothing has
+     * been started. A no-op when there is no upload in flight.
+     */
+    pauseUpload: () => void;
+    /** Continue a paused upload, sending only the windows the store does not have. */
+    resumeUpload: () => void;
+    /** The submit's own failure (a rejected input), or the watch's. */
+    error: string | undefined;
+    /**
+     * Press-to-settle marks for the submission THIS mount made — see
+     * {@link WorkflowSubmissionTiming}. Both `undefined` before the first
+     * `submit()` and again after `reset()`; a run adopted by the mount-time
+     * lookup has no press to time from and sets neither.
+     */
+    timing: WorkflowSubmissionTiming;
+    /**
+     * Who can find the run again after this page is gone — see
+     * {@link WorkflowSubmissionScope}. Derived from the hook's options (`key`,
+     * `recover`), so a page never restates it; `<WorkflowPendingNote>` reads it.
+     */
+    scope: WorkflowSubmissionScope;
+};
+/**
+ * The submission `useWorkflowSubmit<D>` / `useWorkflowStream<D>` hands back for
+ * the workflow def `D`, named so a component can take one as a prop.
+ *
+ * The hook's own return is inferred, so a page that renders everything in one
+ * function never needs this. A page that splits does, and there was no way to
+ * write it from the outside without three names — `WorkflowSubmission`,
+ * `WorkflowOutputOf` and `SubmitInputOf` — composed by hand, which is what a
+ * `ReturnType<typeof useWorkflowSubmit>` cannot say because the hook is
+ * generic. `podcast-digest-workflow`'s `client.tsx` composed exactly that.
+ *
+ * @example
+ * ```tsx
+ * // file: agent.ts
+ * import { agent, workflow } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * export const dailyDigest = workflow({
+ *   input: z.object({ hour: z.number() }),
+ *   output: z.object({ posted: z.string() }),
+ *   run: async ({ hour }) => ({ posted: `daily at ${hour}:00` }),
+ * });
+ *
+ * export default agent({ name: "Digest", workflows: { dailyDigest } });
+ *
+ * // file: client.tsx
+ * import type { WorkflowSubmissionOf } from "@alexkroman1/aai-ui";
+ * import type { dailyDigest } from "./agent.ts";
+ *
+ * function ScheduleControls({ submission }: { submission: WorkflowSubmissionOf<typeof dailyDigest> }) {
+ *   return submission.run?.status === "completed" ? <p>{submission.run.output.posted}</p> : null;
+ * }
+ * ```
+ *
+ * @public
+ */
+export type WorkflowSubmissionOf<D> = WorkflowSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.7.0",
     "xstate": "^5.33.2",
-    "@alexkroman1/aai": "0.17.0"
+    "@alexkroman1/aai": "0.18.0"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",

package/dist/default-client/assets/audio-Ct7JpSNT.js

@@ -1 +0,0 @@
-import{a as e,i as t,t as n}from"./index-BlUYCTB5.js";var r={echoCancellation:!0,noiseSuppression:!1,autoGainControl:!1,voiceIsolation:!1};function i(e,t,n){if(e!==t)throw Error(`Browser refused the ${n} sample rate: asked for ${t} Hz, got ${e} Hz`)}function a(e){let t=Error(`Audio ${e} worklet crashed`);return console.error(`[aai-ui]`,t.message),t}function o(e){e.then(e=>{for(let t of e.getTracks())t.stop()}).catch(()=>{})}function s(e,t,n){let r=new AudioWorkletNode(e,`capture-processor`,{channelCount:1,channelCountMode:`explicit`}),i=null;return r.port.onmessage=e=>{let r=e.data;r.event===`chunk`&&r.buffer?t(r.buffer):r.event===`silent`?n?.():r.event===`stopped`&&(i?.(),i=null)},{node:r,start(){r.port.postMessage({event:`start`})},stop(){let{promise:e,resolve:t}=Promise.withResolvers(),n=setTimeout(t,250);return i=()=>{clearTimeout(n),t()},r.port.postMessage({event:`stop`}),e}}}async function c(e){let{sampleRate:t,captureWorkletSrc:n,maxSeconds:a}=e,c=new AudioContext({sampleRate:t,latencyHint:`interactive`}),l=navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...r}}),u;try{[u]=await Promise.all([l,c.resume(),c.audioWorklet.addModule(n)]),i(c.sampleRate,t,`capture`)}catch(e){throw o(l),await c.close().catch(()=>{}),e}let d=Math.round(t*a)*2,f=[],p=0,m=!1,h=null,g=c.createMediaStreamSource(u),_=s(c,e=>{if(h){h.onChunk(e);return}for(f.push(e),p+=e.byteLength;p>d&&f.length>1;)p-=f.shift()?.byteLength??0},()=>{h?h.onSilent?.():m=!0});g.connect(_.node),_.start();let v=()=>{let e=f;return f=[],p=0,e},y=!1,b=async()=>{y||(y=!0,g.disconnect(),_.node.disconnect(),await c.close().catch(e=>{console.warn(`AudioContext close failed:`,e)}))};return{sampleRate:t,stream:u,ctx:c,handOff(e){h=e;let t=v();return t.length>0&&e.onBuffered(t),m&&e.onSilent?.(),{mic:g,capture:_}},async detach(){return await _.stop(),await b(),{chunks:v(),sampleRate:t}},async close(){y||await _.stop();for(let e of u.getTracks())e.stop();await b()}}}function l(e){let t=new Int16Array(e.length);for(let n=0;n<e.length;n++){let r=Math.max(-1,Math.min(1,e[n]??0));t[n]=r<0?r*32768:r*32767}return t.buffer}async function u(e,t,r){let i=e.reduce((e,t)=>e+t.byteLength/2,0);if(i===0)return[];if(t===r)return e;try{let a=Math.round(i*r/t),o=new OfflineAudioContext(1,a,r),s=o.createBuffer(1,i,t),c=s.getChannelData(0),u=0;for(let t of e)for(let e of new Int16Array(t))c[u++]=e/32768;let d=o.createBufferSource();d.buffer=s,d.connect(o.destination),d.start();let f=(await o.startRendering()).getChannelData(0),p=Math.max(1,Math.round(r*n)),m=[];for(let e=0;e<f.length;e+=p)m.push(l(f.subarray(e,e+p)));return m}catch(e){return console.warn(`[aai-ui] pre-connect audio dropped: resample failed`,e),[]}}async function d(e,t,n){let r=e.createMediaStreamSource(t),i=s(e,n.onMicData,n.onMicSilent);if(r.connect(i.node),n.buffered){let{chunks:t,sampleRate:r}=n.buffered,i=await u(t,r,e.sampleRate);i.length>0&&n.onBuffered(i)}return i.start(),{mic:r,capture:i}}async function f(n){let{sttSampleRate:s,ttsSampleRate:c,captureWorkletSrc:l,playbackWorkletSrc:u,onMicData:f,onError:p,onPlaybackStats:m,onPlaybackProgress:h,onMicSilent:g,preConnect:_}=n,v=n.onPreConnectAudio??(e=>{for(let t of e)f(t)}),y=_?.sampleRate===s?_:null,b=_&&!y?await _.detach():null,x=new AudioContext({sampleRate:c,latencyHint:`playback`}),S=!y&&s===c,C=y?.ctx??(S?x:new AudioContext({sampleRate:s,latencyHint:`interactive`}));async function w(){let e=S?[x]:[x,C];await Promise.all(e.map(e=>e.close().catch(e=>{console.warn(`AudioContext close failed:`,e)})))}let T=_?Promise.resolve(_.stream):navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...r}}),E;try{[E]=await Promise.all([T,x.resume(),C.resume(),y?void 0:C.audioWorklet.addModule(l),x.audioWorklet.addModule(u)]),i(C.sampleRate,s,`capture`),i(x.sampleRate,c,`playback`)}catch(e){throw o(T),await w(),e}let{mic:D,capture:O}=y?y.handOff({onBuffered:v,onChunk:f,onSilent:g}):await d(C,E,{onMicData:f,onMicSilent:g,buffered:b,onBuffered:v});O.node.onprocessorerror=()=>p?.(a(`capture`));let k=null,A=0,j=null,M=new AbortController;function N(){let e=j;j=null,e?.settle()}function P(e){e.stats&&e.stats.concealedSamples>0&&m?.(e.stats),e.reason!==`interrupt`&&(j===null||e.turn===j.turn)&&N()}function F(){if(k)return k;let e=new AudioWorkletNode(x,`playback-processor`);return e.connect(x.destination),e.port.onmessage=e=>{e.data.event===`stop`?P(e.data):e.data.event===`progress`&&h?.(e.data.bufferedMs)},e.onprocessorerror=()=>{let e=a(`playback`);N(),p?.(e)},k=e,e}let I={enqueue(e){M.signal.aborted||e.byteLength!==0&&F().port.postMessage({event:`write`,buffer:new Uint8Array(e)},[e])},done(){if(!k)return Promise.resolve();let n=++A;if(k.port.postMessage({event:`done`,turn:n}),x.state!==`running`)return N(),Promise.resolve();let{promise:r,resolve:i}=Promise.withResolvers();N();let a=()=>{clearInterval(o),clearTimeout(s),j?.settle===a&&(j=null),i()},o=setInterval(()=>{x.state!==`running`&&a()},e),s=setTimeout(a,t);return j={turn:n,settle:a},r},flush(){k&&(N(),k.port.postMessage({event:`interrupt`}))},async close(){if(!M.signal.aborted){M.abort(),await O.stop(),D.disconnect(),O.node.disconnect(),k&&k.disconnect();for(let e of E.getTracks())e.stop();await w()}},async[Symbol.asyncDispose](){await I.close()}};return I}export{f as createVoiceIO,c as openPreConnectCapture};