@owlmeans/client-job 0.1.18-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @owlmeans/client-job
+
+The browser half of a job feed: a state store holding `JobRecord`s, hooks to read it, and one
+socket subscription that keeps it current. It addresses the entrypoints
+[`@owlmeans/server-job`](../server-job) declares.
+
+## Overview
+
+- `appendJobs(context, alias?)` — register the job store on the client context
+- `useJob(id)` / `useJobs(filter)` — live reads over that store
+- `useJobFeed(opts?)` — one socket plus one seeding list call; mount it ONCE per screen
+- `applyJobEvent(store, event)` — the fold, for a feed of your own
+
+## Installation
+
+```bash
+bun add @owlmeans/client-job@^0.1.18-rc.0
+```
+
+## Usage
+
+```typescript
+import { appendJobs } from '@owlmeans/client-job'
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeBasicContext<C, T>(cfg)
+  appendJobs<C, T>(context)
+  return context
+}
+```
+
+```tsx
+import { useJobFeed, useJobs } from '@owlmeans/client-job'
+import { JobProgress, JobStatus, useJobToasts } from '@owlmeans/web-panel/jobs'
+import { JobState } from '@owlmeans/queue'
+
+export const Jobs: FC = () => {
+  const { seeded } = useJobFeed({ root: REPORTS })
+  const jobs = useJobs({ state: [JobState.Waiting, JobState.Active] })
+  useJobToasts(jobs.map(job => job.record))
+
+  return seeded
+    ? <ul>{jobs.map(job => <li key={job.id}>
+      <JobStatus job={job.record} /><JobProgress job={job.record} />
+    </li>)}</ul>
+    : <Spinner/>
+}
+```
+
+## The one gotcha
+
+`useJobFeed` opens a socket per call. Mount it once, high enough that everything showing jobs sits
+under it, and read the store everywhere else — a second feed makes the server push every event
+twice and doubles what the screen reacts to.
+
+## Depends On
+
+- [`@owlmeans/state`](../state) — the store; [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList`
+- [`@owlmeans/client-auth`](../client-auth) — `useWs`, which puts the token on the socket query
+- [`@owlmeans/queue`](../queue) — `JobRecord`, `JobEvent`, `JobState`
+
+## Related
+
+- [`@owlmeans/server-job`](../server-job) — the entrypoints this addresses
+- [`@owlmeans/web-panel`](../web-panel) `./jobs` — the components to render what it collects
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.12
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/client-job",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-04T22:43:25.447Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "client-job",
+      "category": "package-specific",
+      "file": "skills/client-job/SKILL.md",
+      "canonicalPath": ".agents/skills/client-job/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/client-job/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: client-job
+description: How to use @owlmeans/client-job — appendJobs() to register the job store, useJob/useJobs to read it, and useJobFeed() to mount the socket subscription and seed it from the list entrypoint. Auto-invoked when showing queue job progress in a browser client or importing job hooks.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/client-job
+
+**Layer:** Client
+**Install:** `"@owlmeans/client-job": "^0.1.18-rc.0"` in `dependencies`
+
+The browser half of a job feed. It holds `JobRecord`s in a `@owlmeans/state` store, keeps that
+store current from the entrypoints `@owlmeans/server-job` declares, and hands screens the ordinary
+state hooks. Rendering is `@owlmeans/web-panel/jobs`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `appendJobs(context, alias?)` | Register the job store on the client context |
+| `useJob(id?, resource?)` | One job, live — an unknown or absent id yields an `empty` model, never a throw |
+| `useJobs(filter?, opts?)` | A live query over the store, newest first unless `opts.sort` says otherwise |
+| `useJobFeed(opts?)` | Mount the socket and seed the store. **Once per screen** |
+| `applyJobEvent(store, event)` | The fold one `JobEvent` performs, for a feed of your own |
+| `jobEntrypointAliases(root?)` | `{ base, list, get, cancel, watch }` — the same shape the server declares |
+| `JobFeed` / `JobFeedOptions` / `UseJobsOptions` / `JobFilter` | What the feed reports, and the option shapes |
+| `JOBS` | The store's alias (`job-state`), typed as `StateAlias<JobRecord>` |
+| Constants | `DEFAULT_JOB_ROOT` (`jobs`), `JOB_EVENT` (`job-event`) |
+
+## Wiring
+
+```typescript
+import { appendJobs } from '@owlmeans/client-job'
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeBasicContext<C, T>(cfg)
+  appendJobs<C, T>(context)
+  return context
+}
+```
+
+Jobs get a store of their own rather than the context's default one: a job id is the broker's, and
+sharing an id space with the app's records is how a completed job overwrites an unrelated row.
+`appendJobs` is idempotent like every `append*`.
+
+## Reading
+
+```tsx
+const { seeded, connected, error } = useJobFeed({ root: REPORTS, query: { size: 50 } })
+
+const running = useJobs({ state: [JobState.Waiting, JobState.Active] })
+const mine = useJobs({ 'data.target': projectId })
+const one = useJob(id)
+```
+
+The criteria language is the resource one, so a filter written for the list entrypoint means the
+same thing applied locally, and a dotted key reaches into the payload. `seeded` is what tells "no
+jobs" apart from "not loaded yet" — `useJob` answers an `empty` model for an id the store has not
+seen, which is a loading state and not an error. `connected` says the socket is open and `error`
+carries whatever the seeding call threw, so a screen can distinguish a failed load from an empty
+one. `JobFeedOptions` also takes `resource` for a store other than `JOBS`, and a `query` narrowing
+the seeding call — compared by CONTENT, so a fresh object literal per render does not re-fetch
+while a changed filter does re-seed.
+
+## What `useJobFeed` does
+
+1. Opens the watch socket through `@owlmeans/client-auth`'s `useWs`, which puts the current token
+   on the connection query — the watch entrypoint is guarded, and the server derives ownership
+   from that token.
+2. Calls the list entrypoint once and writes the answer with **`store.replace`**, not a run of
+   saves: it is the server saying what exists, so a job cancelled from another tab has to LEAVE the
+   store, and one write wakes the subscribers once instead of once per record.
+3. Folds each `JobEvent` frame in with `applyJobEvent` — merged over the record the store holds,
+   because an event carries only what changed while `save` replaces. An event for an id the store
+   never saw still writes a row, so a job enqueued in another tab reports its progress here and the
+   next seeding call fills in the rest.
+
+Two details the fold gets right and a hand-written one usually does not: a progress frame never
+moves a settled job back to `Active` (the completion and the last progress ping race), and an empty
+`JobEvent.name` never overwrites a known one (the contract sends empty when the job is already
+gone).
+
+## The one gotcha
+
+**`useJobFeed` opens a socket per call.** Mount it once, high enough that everything showing jobs
+sits under it, and read the store everywhere else. Two feeds make the server push every event twice
+and re-seed over each other.
+
+## Depends On
+
+- `@owlmeans/state` — the store, `replace` and the `StateModel` commit rules
+- `@owlmeans/client` — `useStoreModel`, `useStoreList`, `useContext`
+- `@owlmeans/client-auth` — `useWs` (the token-carrying socket)
+- `@owlmeans/queue` — `JobRecord`, `JobEvent`, `JobState`, `isSettled`
+
+## Related
+
+- `server-job` — the entrypoints this addresses, and the ownership rule that decides what arrives
+- `state` — the store contract; `client-socket` — how the connection is addressed
+- `web-panel` — `./jobs` (`JobProgress`, `JobStatus`, `useJobToasts`)

package/build/consts.d.ts

@@ -0,0 +1,15 @@
+import type { JobRecord } from '@owlmeans/queue';
+import type { StateAlias } from '@owlmeans/state';
+/** The store this package registers and every hook here reads. */
+export declare const JOBS: StateAlias<JobRecord>;
+/**
+ * The alias root a group answers under when a caller names none — the same default
+ * `@owlmeans/server-job` declares with.
+ *
+ * That package's `<root>` / `<root>:<verb>` alias shape and its `job-event` frame name are the
+ * whole contract between the two halves. They are restated here rather than imported because the
+ * server half pulls fastify in, and a browser bundle must not.
+ */
+export declare const DEFAULT_JOB_ROOT = "jobs";
+export declare const JOB_EVENT = "job-event";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,kEAAkE;AAClE,eAAO,MAAM,IAAI,EAAE,UAAU,CAAC,SAAS,CAAsC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAEtC,eAAO,MAAM,SAAS,cAAc,CAAA"}

package/build/consts.js

@@ -0,0 +1,14 @@
+import { stateAlias } from '@owlmeans/state';
+/** The store this package registers and every hook here reads. */
+export const JOBS = stateAlias('job-state');
+/**
+ * The alias root a group answers under when a caller names none — the same default
+ * `@owlmeans/server-job` declares with.
+ *
+ * That package's `<root>` / `<root>:<verb>` alias shape and its `job-event` frame name are the
+ * whole contract between the two halves. They are restated here rather than imported because the
+ * server half pulls fastify in, and a browser bundle must not.
+ */
+export const DEFAULT_JOB_ROOT = 'jobs';
+export const JOB_EVENT = 'job-event';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAG5C,kEAAkE;AAClE,MAAM,CAAC,MAAM,IAAI,GAA0B,UAAU,CAAY,WAAW,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAEtC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAA"}

package/build/feed.d.ts

@@ -0,0 +1,15 @@
+import type { JobFeed, JobFeedOptions } from './types.js';
+/**
+ * Mount the job feed: one socket, seeded once from the list entrypoint.
+ *
+ * Mount it ONCE per screen that shows jobs — every call opens its own socket, and two feeds mean
+ * the server fans the same events out twice. Everything else reads the store through
+ * {@link useJob} / {@link useJobs}, so nothing else in the tree needs the connection.
+ *
+ * The seed is `replace`, not a run of saves: it is the server saying what exists, so a job
+ * cancelled from another tab has to LEAVE the store, and one write wakes the subscribers once.
+ * The socket is opened by `@owlmeans/client-auth`'s `useWs`, which puts the current token on the
+ * connection query — the watch entrypoint is guarded, and ownership is derived from that token.
+ */
+export declare const useJobFeed: (opts?: JobFeedOptions) => JobFeed;
+//# sourceMappingURL=feed.d.ts.map

package/build/feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.d.ts","sourceRoot":"","sources":["../src/feed.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAmB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAG1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,UAAW,cAAc,KAAG,OAkDlD,CAAA"}

package/build/feed.js

@@ -0,0 +1,65 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useContext } from '@owlmeans/client';
+import { useWs } from '@owlmeans/client-auth';
+import { DEFAULT_JOB_ROOT, JOBS, JOB_EVENT } from './consts.js';
+import { jobEntrypointAliases } from './helper.js';
+import { applyJobEvent } from './utils/index.js';
+/**
+ * Mount the job feed: one socket, seeded once from the list entrypoint.
+ *
+ * Mount it ONCE per screen that shows jobs — every call opens its own socket, and two feeds mean
+ * the server fans the same events out twice. Everything else reads the store through
+ * {@link useJob} / {@link useJobs}, so nothing else in the tree needs the connection.
+ *
+ * The seed is `replace`, not a run of saves: it is the server saying what exists, so a job
+ * cancelled from another tab has to LEAVE the store, and one write wakes the subscribers once.
+ * The socket is opened by `@owlmeans/client-auth`'s `useWs`, which puts the current token on the
+ * connection query — the watch entrypoint is guarded, and ownership is derived from that token.
+ */
+export const useJobFeed = (opts) => {
+    const context = useContext();
+    const alias = opts?.resource ?? JOBS;
+    const aliases = useMemo(() => jobEntrypointAliases(opts?.root ?? DEFAULT_JOB_ROOT), [opts?.root]);
+    const connection = useWs(aliases.watch);
+    const [seed, setSeed] = useState({ seeded: false, error: null });
+    // The seeding query is compared by CONTENT: a screen that narrows its filter re-seeds, while a
+    // caller passing a fresh object literal every render does not re-fetch on every render.
+    const query = JSON.stringify(opts?.query ?? null);
+    useEffect(() => {
+        let live = true;
+        void (async () => {
+            try {
+                const result = await context.entrypoint(aliases.list)
+                    .call({ query: opts?.query });
+                if (!live) {
+                    return;
+                }
+                await context.getStateResource(alias).replace(result.items);
+                setSeed({ seeded: true, error: null });
+            }
+            catch (e) {
+                if (live) {
+                    setSeed({ seeded: false, error: e });
+                }
+            }
+        })();
+        return () => { live = false; };
+    }, [context, aliases.list, alias, query]);
+    useEffect(() => {
+        if (connection == null) {
+            return;
+        }
+        const store = context.getStateResource(alias);
+        const unsubscribe = connection.observe(JOB_EVENT, async (message) => {
+            try {
+                await applyJobEvent(store, message.payload);
+            }
+            catch (e) {
+                console.error('Job feed apply error:', e);
+            }
+        });
+        return () => unsubscribe();
+    }, [connection, context, alias]);
+    return { connected: connection != null, ...seed };
+};
+//# sourceMappingURL=feed.js.map

package/build/feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.js","sourceRoot":"","sources":["../src/feed.ts"],"names":[],"mappings":"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"}

package/build/helper.d.ts

@@ -0,0 +1,17 @@
+import type { StateAlias } from '@owlmeans/state';
+import type { JobRecord } from '@owlmeans/queue';
+import type { Config, Context, JobEntrypointAliases } from './types.js';
+/**
+ * Register the store the job hooks read.
+ *
+ * Jobs get a store of their own rather than the context's default one because a job id is the
+ * broker's, and sharing an id space with the app's own records is how a completed job overwrites
+ * an unrelated row. Idempotent, like every `append*` — an app that calls it twice keeps whatever
+ * the store already collected.
+ */
+export declare const appendJobs: <C extends Config, T extends Context<C>>(context: T, alias?: StateAlias<JobRecord>) => T;
+/**
+ * The aliases one job group answers under — the same shape `@owlmeans/server-job` declares.
+ */
+export declare const jobEntrypointAliases: (root?: string) => JobEntrypointAliases;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WACtD,CAAC,UAAS,UAAU,CAAC,SAAS,CAAC,KACvC,CAA8D,CAAA;AAEjE;;GAEG;AACH,eAAO,MAAM,oBAAoB,UACzB,MAAM,KACX,oBAMD,CAAA"}

package/build/helper.js

@@ -0,0 +1,22 @@
+import { appendStateResource } from '@owlmeans/state';
+import { DEFAULT_JOB_ROOT, JOBS } from './consts.js';
+/**
+ * Register the store the job hooks read.
+ *
+ * Jobs get a store of their own rather than the context's default one because a job id is the
+ * broker's, and sharing an id space with the app's own records is how a completed job overwrites
+ * an unrelated row. Idempotent, like every `append*` — an app that calls it twice keeps whatever
+ * the store already collected.
+ */
+export const appendJobs = (context, alias = JOBS) => appendStateResource(context, alias);
+/**
+ * The aliases one job group answers under — the same shape `@owlmeans/server-job` declares.
+ */
+export const jobEntrypointAliases = (root = DEFAULT_JOB_ROOT) => ({
+    base: root,
+    list: `${root}:list`,
+    get: `${root}:get`,
+    cancel: `${root}:cancel`,
+    watch: `${root}:watch`,
+});
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAGrD,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,OAAU,EAAE,KAAK,GAA0B,IAAI,EAC5C,EAAE,CAAC,mBAAmB,CAAkB,OAAO,EAAE,KAAK,CAAM,CAAA;AAEjE;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,IAAI,GAAW,gBAAgB,EACT,EAAE,CAAC,CAAC;IAC1B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,GAAG,IAAI,OAAO;IACpB,GAAG,EAAE,GAAG,IAAI,MAAM;IAClB,MAAM,EAAE,GAAG,IAAI,SAAS;IACxB,KAAK,EAAE,GAAG,IAAI,QAAQ;CACvB,CAAC,CAAA"}

package/build/hooks.d.ts

@@ -0,0 +1,18 @@
+import type { StateModel } from '@owlmeans/state';
+import type { JobRecord } from '@owlmeans/queue';
+import type { JobFilter, UseJobsOptions } from './types.js';
+/**
+ * One job, live.
+ *
+ * Never throws for an id the store has not seen — the model comes back `empty`, which is what a
+ * screen renders as "still loading" while {@link useJobFeed} seeds.
+ */
+export declare const useJob: <D = unknown, R = unknown>(id?: string, resource?: string) => StateModel<JobRecord<D, R>>;
+/**
+ * A live query over the job store, newest first unless told otherwise.
+ *
+ * The criteria is the resource language, so a filter written for the list entrypoint means the
+ * same thing here: `{ state: JobState.Active }`, `{ name: 'report:build' }`, `{ 'data.target': id }`.
+ */
+export declare const useJobs: <D = unknown, R = unknown>(filter?: JobFilter<D, R>, opts?: UseJobsOptions<D, R>) => StateModel<JobRecord<D, R>>[];
+//# sourceMappingURL=hooks.d.ts.map

package/build/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,OACxC,MAAM,aAAY,MAAM,KAC5B,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAiD,CAAA;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,WACrC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,KACpD,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAI5B,CAAA"}

package/build/hooks.js

@@ -0,0 +1,21 @@
+import { useStoreList, useStoreModel } from '@owlmeans/client';
+import { JOBS } from './consts.js';
+/**
+ * One job, live.
+ *
+ * Never throws for an id the store has not seen — the model comes back `empty`, which is what a
+ * screen renders as "still loading" while {@link useJobFeed} seeds.
+ */
+export const useJob = (id, resource = JOBS) => useStoreModel(id, resource);
+/**
+ * A live query over the job store, newest first unless told otherwise.
+ *
+ * The criteria is the resource language, so a filter written for the list entrypoint means the
+ * same thing here: `{ state: JobState.Active }`, `{ name: 'report:build' }`, `{ 'data.target': id }`.
+ */
+export const useJobs = (filter, opts) => useStoreList({
+    query: filter,
+    sort: opts?.sort ?? [{ field: 'createdAt', order: 'desc' }],
+    resource: opts?.resource ?? JOBS,
+});
+//# sourceMappingURL=hooks.js.map

package/build/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAG9D,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGlC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,EAAW,EAAE,QAAQ,GAAW,IAAI,EACP,EAAE,CAAC,aAAa,CAAkB,EAAE,EAAE,QAAQ,CAAC,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,MAAwB,EAAE,IAA2B,EACtB,EAAE,CAAC,YAAY,CAAkB;IAChE,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC3D,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,IAAI;CACjC,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,7 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './helper.js';
+export * from './hooks.js';
+export * from './feed.js';
+export * from './utils/index.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,kBAAkB,CAAA"}

package/build/index.js

@@ -0,0 +1,6 @@
+export * from './consts.js';
+export * from './helper.js';
+export * from './hooks.js';
+export * from './feed.js';
+export * from './utils/index.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,kBAAkB,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,42 @@
+import type { ClientConfig } from '@owlmeans/client-context';
+import type { ClientContext } from '@owlmeans/client';
+import type { JobRecord } from '@owlmeans/queue';
+import type { Criteria, Sort } from '@owlmeans/resource';
+import type { StateAlias } from '@owlmeans/state';
+export interface Config extends ClientConfig {
+}
+export interface Context<C extends Config = Config> extends ClientContext<C> {
+}
+/** The alias every entrypoint of one job group answers under. */
+export interface JobEntrypointAliases {
+    base: string;
+    list: string;
+    get: string;
+    cancel: string;
+    watch: string;
+}
+export interface UseJobsOptions<D = unknown, R = unknown> {
+    sort?: Sort<JobRecord<D, R>>[];
+    /** Which store to read; the package's own when omitted. */
+    resource?: StateAlias<JobRecord>;
+}
+export interface JobFeedOptions {
+    /** The alias root the group was declared under. */
+    root?: string;
+    resource?: StateAlias<JobRecord>;
+    /** What the seeding list call asks for — `state`, `name`, `page`, `size`. */
+    query?: Record<string, string | number | undefined>;
+}
+/**
+ * Whether the feed is carrying anything yet, so a screen can tell "no jobs" from "not loaded".
+ */
+export interface JobFeed {
+    /** The socket is open. */
+    connected: boolean;
+    /** The authoritative list has been written into the store at least once. */
+    seeded: boolean;
+    /** What the seeding call threw, if it threw. */
+    error: Error | null;
+}
+export type JobFilter<D = unknown, R = unknown> = Criteria<JobRecord<D, R>>;
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,MAAM,WAAW,MAAO,SAAQ,YAAY;CAAI;AAEhD,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI;AAEhF,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACtD,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;IAChC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IACf,gDAAgD;IAChD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/utils/event.d.ts

@@ -0,0 +1,15 @@
+import type { JobEvent, JobRecord } from '@owlmeans/queue';
+import type { StateResource } from '@owlmeans/state';
+/**
+ * Fold one lifecycle frame into the store.
+ *
+ * The frame is merged over whatever the store holds rather than saved as itself: an event carries
+ * only what changed, and `save` replaces the record. An event for an id the store never saw still
+ * writes a row — a job enqueued in another tab reports its progress here too, and the next seeding
+ * call fills in the rest.
+ *
+ * A progress frame does NOT move a settled job back to active: the broker's completion and its
+ * last progress ping race, and the losing order would leave a finished job spinning forever.
+ */
+export declare const applyJobEvent: (store: StateResource<JobRecord>, event: JobEvent) => Promise<void>;
+//# sourceMappingURL=event.d.ts.map

package/build/utils/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/utils/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,UACjB,aAAa,CAAC,SAAS,CAAC,SAAS,QAAQ,KAC/C,OAAO,CAAC,IAAI,CAqBd,CAAA"}

package/build/utils/event.js

@@ -0,0 +1,33 @@
+import { isSettled, JobEventType, JobState } from '@owlmeans/queue';
+/**
+ * Fold one lifecycle frame into the store.
+ *
+ * The frame is merged over whatever the store holds rather than saved as itself: an event carries
+ * only what changed, and `save` replaces the record. An event for an id the store never saw still
+ * writes a row — a job enqueued in another tab reports its progress here too, and the next seeding
+ * call fills in the rest.
+ *
+ * A progress frame does NOT move a settled job back to active: the broker's completion and its
+ * last progress ping race, and the losing order would leave a finished job spinning forever.
+ */
+export const applyJobEvent = async (store, event) => {
+    const known = await store.load(event.id);
+    const change = event.type === JobEventType.Completed
+        ? { state: JobState.Completed, result: event.result }
+        : event.type === JobEventType.Failed
+            ? { state: JobState.Failed, error: event.error }
+            : {
+                progress: event.progress,
+                ...(isSettled(known?.state) ? {} : { state: JobState.Active }),
+            };
+    await store.save({
+        ...(known ?? { data: undefined }),
+        id: event.id,
+        queue: event.queue,
+        // A queue that removed the job has no name left to report — never overwrite a known one
+        // with the empty string the contract sends in its place.
+        ...(event.name !== '' ? { name: event.name } : {}),
+        ...change,
+    });
+};
+//# sourceMappingURL=event.js.map

package/build/utils/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/utils/event.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAGnE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,KAA+B,EAAE,KAAe,EACjC,EAAE;IACjB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAExC,MAAM,MAAM,GAAuB,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,SAAS;QACtE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;QACrD,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,MAAM;YAClC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YAChD,CAAC,CAAC;gBACA,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;aAC/D,CAAA;IAEL,MAAM,KAAK,CAAC,IAAI,CAAC;QACf,GAAG,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,SAAoB,EAAE,CAAC;QAC5C,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,wFAAwF;QACxF,yDAAyD;QACzD,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,MAAM;KACV,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/build/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './event.js';
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/utils/index.js

@@ -0,0 +1,2 @@
+export * from './event.js';
+//# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@owlmeans/client-job",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 126 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/react": "^19.2.17",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@owlmeans/client": "^0.1.18-rc.16",
+    "@owlmeans/client-auth": "^0.1.18-rc.20",
+    "@owlmeans/client-context": "^0.1.18-rc.13",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.13",
+    "@owlmeans/context": "^0.1.18-rc.8",
+    "@owlmeans/queue": "^0.1.18-rc.9",
+    "@owlmeans/resource": "^0.1.18-rc.9",
+    "@owlmeans/socket": "^0.1.18-rc.9",
+    "@owlmeans/state": "^0.1.18-rc.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,18 @@
+import type { JobRecord } from '@owlmeans/queue'
+import { stateAlias } from '@owlmeans/state'
+import type { StateAlias } from '@owlmeans/state'
+
+/** The store this package registers and every hook here reads. */
+export const JOBS: StateAlias<JobRecord> = stateAlias<JobRecord>('job-state')
+
+/**
+ * The alias root a group answers under when a caller names none — the same default
+ * `@owlmeans/server-job` declares with.
+ *
+ * That package's `<root>` / `<root>:<verb>` alias shape and its `job-event` frame name are the
+ * whole contract between the two halves. They are restated here rather than imported because the
+ * server half pulls fastify in, and a browser bundle must not.
+ */
+export const DEFAULT_JOB_ROOT = 'jobs'
+
+export const JOB_EVENT = 'job-event'

package/src/feed.ts

@@ -0,0 +1,74 @@
+import { useEffect, useMemo, useState } from 'react'
+import { useContext } from '@owlmeans/client'
+import { useWs } from '@owlmeans/client-auth'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import type { JobEvent, JobRecord } from '@owlmeans/queue'
+import type { ListResult } from '@owlmeans/resource'
+import { DEFAULT_JOB_ROOT, JOBS, JOB_EVENT } from './consts.js'
+import { jobEntrypointAliases } from './helper.js'
+import type { Config, Context, JobFeed, JobFeedOptions } from './types.js'
+import { applyJobEvent } from './utils/index.js'
+
+/**
+ * Mount the job feed: one socket, seeded once from the list entrypoint.
+ *
+ * Mount it ONCE per screen that shows jobs — every call opens its own socket, and two feeds mean
+ * the server fans the same events out twice. Everything else reads the store through
+ * {@link useJob} / {@link useJobs}, so nothing else in the tree needs the connection.
+ *
+ * The seed is `replace`, not a run of saves: it is the server saying what exists, so a job
+ * cancelled from another tab has to LEAVE the store, and one write wakes the subscribers once.
+ * The socket is opened by `@owlmeans/client-auth`'s `useWs`, which puts the current token on the
+ * connection query — the watch entrypoint is guarded, and ownership is derived from that token.
+ */
+export const useJobFeed = (opts?: JobFeedOptions): JobFeed => {
+  const context = useContext<Config, Context>()
+  const alias = opts?.resource ?? JOBS
+  const aliases = useMemo(
+    () => jobEntrypointAliases(opts?.root ?? DEFAULT_JOB_ROOT), [opts?.root]
+  )
+  const connection = useWs(aliases.watch)
+  const [seed, setSeed] = useState<Pick<JobFeed, 'seeded' | 'error'>>({ seeded: false, error: null })
+  // The seeding query is compared by CONTENT: a screen that narrows its filter re-seeds, while a
+  // caller passing a fresh object literal every render does not re-fetch on every render.
+  const query = JSON.stringify(opts?.query ?? null)
+
+  useEffect(() => {
+    let live = true
+    void (async () => {
+      try {
+        const result = await context.entrypoint<ClientEntrypoint<ListResult<JobRecord>>>(aliases.list)
+          .call<ListResult<JobRecord>>({ query: opts?.query })
+        if (!live) {
+          return
+        }
+        await context.getStateResource(alias).replace(result.items)
+        setSeed({ seeded: true, error: null })
+      } catch (e) {
+        if (live) {
+          setSeed({ seeded: false, error: e as Error })
+        }
+      }
+    })()
+
+    return () => { live = false }
+  }, [context, aliases.list, alias, query])
+
+  useEffect(() => {
+    if (connection == null) {
+      return
+    }
+    const store = context.getStateResource(alias)
+    const unsubscribe = connection.observe<JobEvent>(JOB_EVENT, async message => {
+      try {
+        await applyJobEvent(store, message.payload)
+      } catch (e) {
+        console.error('Job feed apply error:', e)
+      }
+    })
+
+    return () => unsubscribe()
+  }, [connection, context, alias])
+
+  return { connected: connection != null, ...seed }
+}

package/src/helper.ts

@@ -0,0 +1,30 @@
+import { appendStateResource } from '@owlmeans/state'
+import type { StateAlias } from '@owlmeans/state'
+import type { JobRecord } from '@owlmeans/queue'
+import { DEFAULT_JOB_ROOT, JOBS } from './consts.js'
+import type { Config, Context, JobEntrypointAliases } from './types.js'
+
+/**
+ * Register the store the job hooks read.
+ *
+ * Jobs get a store of their own rather than the context's default one because a job id is the
+ * broker's, and sharing an id space with the app's own records is how a completed job overwrites
+ * an unrelated row. Idempotent, like every `append*` — an app that calls it twice keeps whatever
+ * the store already collected.
+ */
+export const appendJobs = <C extends Config, T extends Context<C>>(
+  context: T, alias: StateAlias<JobRecord> = JOBS
+): T => appendStateResource<C, T, JobRecord>(context, alias) as T
+
+/**
+ * The aliases one job group answers under — the same shape `@owlmeans/server-job` declares.
+ */
+export const jobEntrypointAliases = (
+  root: string = DEFAULT_JOB_ROOT
+): JobEntrypointAliases => ({
+  base: root,
+  list: `${root}:list`,
+  get: `${root}:get`,
+  cancel: `${root}:cancel`,
+  watch: `${root}:watch`,
+})

package/src/hooks.ts

@@ -0,0 +1,29 @@
+import { useStoreList, useStoreModel } from '@owlmeans/client'
+import type { StateModel } from '@owlmeans/state'
+import type { JobRecord } from '@owlmeans/queue'
+import { JOBS } from './consts.js'
+import type { JobFilter, UseJobsOptions } from './types.js'
+
+/**
+ * One job, live.
+ *
+ * Never throws for an id the store has not seen — the model comes back `empty`, which is what a
+ * screen renders as "still loading" while {@link useJobFeed} seeds.
+ */
+export const useJob = <D = unknown, R = unknown>(
+  id?: string, resource: string = JOBS
+): StateModel<JobRecord<D, R>> => useStoreModel<JobRecord<D, R>>(id, resource)
+
+/**
+ * A live query over the job store, newest first unless told otherwise.
+ *
+ * The criteria is the resource language, so a filter written for the list entrypoint means the
+ * same thing here: `{ state: JobState.Active }`, `{ name: 'report:build' }`, `{ 'data.target': id }`.
+ */
+export const useJobs = <D = unknown, R = unknown>(
+  filter?: JobFilter<D, R>, opts?: UseJobsOptions<D, R>
+): StateModel<JobRecord<D, R>>[] => useStoreList<JobRecord<D, R>>({
+  query: filter,
+  sort: opts?.sort ?? [{ field: 'createdAt', order: 'desc' }],
+  resource: opts?.resource ?? JOBS,
+})

package/src/index.ts

@@ -0,0 +1,7 @@
+export type * from './types.js'
+
+export * from './consts.js'
+export * from './helper.js'
+export * from './hooks.js'
+export * from './feed.js'
+export * from './utils/index.js'

package/src/types.ts

@@ -0,0 +1,46 @@
+import type { ClientConfig } from '@owlmeans/client-context'
+import type { ClientContext } from '@owlmeans/client'
+import type { JobRecord } from '@owlmeans/queue'
+import type { Criteria, Sort } from '@owlmeans/resource'
+import type { StateAlias } from '@owlmeans/state'
+
+export interface Config extends ClientConfig { }
+
+export interface Context<C extends Config = Config> extends ClientContext<C> { }
+
+/** The alias every entrypoint of one job group answers under. */
+export interface JobEntrypointAliases {
+  base: string
+  list: string
+  get: string
+  cancel: string
+  watch: string
+}
+
+export interface UseJobsOptions<D = unknown, R = unknown> {
+  sort?: Sort<JobRecord<D, R>>[]
+  /** Which store to read; the package's own when omitted. */
+  resource?: StateAlias<JobRecord>
+}
+
+export interface JobFeedOptions {
+  /** The alias root the group was declared under. */
+  root?: string
+  resource?: StateAlias<JobRecord>
+  /** What the seeding list call asks for — `state`, `name`, `page`, `size`. */
+  query?: Record<string, string | number | undefined>
+}
+
+/**
+ * Whether the feed is carrying anything yet, so a screen can tell "no jobs" from "not loaded".
+ */
+export interface JobFeed {
+  /** The socket is open. */
+  connected: boolean
+  /** The authoritative list has been written into the store at least once. */
+  seeded: boolean
+  /** What the seeding call threw, if it threw. */
+  error: Error | null
+}
+
+export type JobFilter<D = unknown, R = unknown> = Criteria<JobRecord<D, R>>

package/src/utils/event.ts

@@ -0,0 +1,39 @@
+import type { JobEvent, JobRecord } from '@owlmeans/queue'
+import { isSettled, JobEventType, JobState } from '@owlmeans/queue'
+import type { StateResource } from '@owlmeans/state'
+
+/**
+ * Fold one lifecycle frame into the store.
+ *
+ * The frame is merged over whatever the store holds rather than saved as itself: an event carries
+ * only what changed, and `save` replaces the record. An event for an id the store never saw still
+ * writes a row — a job enqueued in another tab reports its progress here too, and the next seeding
+ * call fills in the rest.
+ *
+ * A progress frame does NOT move a settled job back to active: the broker's completion and its
+ * last progress ping race, and the losing order would leave a finished job spinning forever.
+ */
+export const applyJobEvent = async (
+  store: StateResource<JobRecord>, event: JobEvent
+): Promise<void> => {
+  const known = await store.load(event.id)
+
+  const change: Partial<JobRecord> = event.type === JobEventType.Completed
+    ? { state: JobState.Completed, result: event.result }
+    : event.type === JobEventType.Failed
+      ? { state: JobState.Failed, error: event.error }
+      : {
+        progress: event.progress,
+        ...(isSettled(known?.state) ? {} : { state: JobState.Active }),
+      }
+
+  await store.save({
+    ...(known ?? { data: undefined as unknown }),
+    id: event.id,
+    queue: event.queue,
+    // A queue that removed the job has no name left to report — never overwrite a known one
+    // with the empty string the contract sends in its place.
+    ...(event.name !== '' ? { name: event.name } : {}),
+    ...change,
+  })
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './event.js'

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.react.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+}