@entifix/next-shell 0.1.0-0

package/dist/lib/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/session/index.ts"],"sourcesContent":["// Client-safe session helpers only.\n//\n// The cookie writers, the refresh route handler AND the account-link builders\n// ship from `@entifix/next-shell/server` instead. The link builders are\n// pure functions, but everything reachable from this entry is stamped\n// `\"use client\"` by the bundler — so exporting them here turns a plain function\n// call in a server layout into \"Attempted to call accountPaths() from the\n// server but accountPaths is on the client\".\nexport * from './session-keepalive.js';\nexport * from './use-session-refresh.js';\n"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,sEAAsE;AACtE,gFAAgF;AAChF,0EAA0E;AAC1E,6CAA6C;AAC7C,cAAc,yBAAyB;AACvC,cAAc,2BAA2B"}

package/dist/lib/session/refresh-route.d.ts

@@ -0,0 +1,19 @@
+import { type NextRequest, NextResponse } from 'next/server';
+export interface RefreshRouteOptions {
+    /** auth-service base URL; defaults to `AUTH_SERVICE_URL` then :3102. */
+    readonly authServiceUrl?: string;
+}
+/**
+ * Builds `POST /api/auth/refresh` for an `-app`.
+ *
+ * Every app needs its own copy of this route because cookies are per-origin: in
+ * production each `-app` is a different host and mints its own, and only
+ * localhost's shared hostname makes it look otherwise. So the *handler* is
+ * shared from here and each app mounts it.
+ *
+ * A dead session clears the cookies rather than leaving them to rot — otherwise
+ * the browser keeps presenting a session id that will never refresh again, and
+ * the middleware keeps believing there is a session to protect.
+ */
+export declare const createRefreshRoute: (options?: RefreshRouteOptions) => (request: NextRequest) => Promise<NextResponse>;
+//# sourceMappingURL=refresh-route.d.ts.map

package/dist/lib/session/refresh-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-route.d.ts","sourceRoot":"","sources":["../../../src/lib/session/refresh-route.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAW7D,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAiCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC5B,UAAS,mBAAwB,MAC3B,SAAS,WAAW,KAAG,OAAO,CAAC,YAAY,CAgDjD,CAAC"}

package/dist/lib/session/refresh-route.js

@@ -0,0 +1,85 @@
+import { SESSION_COOKIE } from '@entifix/core';
+import { NextResponse } from 'next/server';
+import { applySessionCookies, clearSessionCookies } from './cookies.js';
+/**
+ * In-flight refreshes, keyed by session id.
+ *
+ * Several tabs and a lazy server-side refresh can all notice an expiring token
+ * within the same second. Collapsing them costs one map and saves the round
+ * trips. It is deliberately per-process and not the Redis `LockService`: session
+ * ids do not rotate, so the worst a lost race can do is mint a second, equally
+ * valid token — a wasted signature, not a correctness problem.
+ */ const inFlight = new Map();
+const refreshOnce = (authServiceUrl, sessionId)=>{
+    const existing = inFlight.get(sessionId);
+    if (existing !== undefined) return existing;
+    const pending = fetch(`${authServiceUrl}/api/auth/refresh`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+            sessionId
+        }),
+        cache: 'no-store'
+    }).finally(()=>{
+        inFlight.delete(sessionId);
+    });
+    inFlight.set(sessionId, pending);
+    return pending;
+};
+/**
+ * Builds `POST /api/auth/refresh` for an `-app`.
+ *
+ * Every app needs its own copy of this route because cookies are per-origin: in
+ * production each `-app` is a different host and mints its own, and only
+ * localhost's shared hostname makes it look otherwise. So the *handler* is
+ * shared from here and each app mounts it.
+ *
+ * A dead session clears the cookies rather than leaving them to rot — otherwise
+ * the browser keeps presenting a session id that will never refresh again, and
+ * the middleware keeps believing there is a session to protect.
+ */ export const createRefreshRoute = (options = {})=>async (request)=>{
+        var _ref, _options_authServiceUrl;
+        var _request_cookies_get;
+        const authServiceUrl = (_ref = (_options_authServiceUrl = options.authServiceUrl) != null ? _options_authServiceUrl : process.env.AUTH_SERVICE_URL) != null ? _ref : 'http://localhost:3102';
+        const sessionId = (_request_cookies_get = request.cookies.get(SESSION_COOKIE)) == null ? void 0 : _request_cookies_get.value;
+        if (sessionId === undefined) {
+            return NextResponse.json({
+                error: 'no session',
+                code: 'unauthenticated'
+            }, {
+                status: 401
+            });
+        }
+        const upstream = await refreshOnce(authServiceUrl, sessionId).catch(()=>undefined);
+        if (upstream === undefined) {
+            // The service is unreachable. The session may well still be fine, so the
+            // cookies stay and the client is told to retry rather than sign out.
+            return NextResponse.json({
+                error: 'auth service unreachable',
+                code: 'network'
+            }, {
+                status: 503
+            });
+        }
+        // `clone()` because a collapsed refresh hands the same Response to every
+        // waiter, and a body can only be read once.
+        const data = await upstream.clone().json();
+        if (!upstream.ok) {
+            return clearSessionCookies(NextResponse.json(data, {
+                status: upstream.status
+            }));
+        }
+        const payload = data;
+        return applySessionCookies(NextResponse.json({
+            ok: true,
+            expiresIn: payload.expiresIn,
+            sessionExpiresIn: payload.sessionExpiresIn
+        }), {
+            accessToken: payload.accessToken,
+            sessionExpiresIn: payload.sessionExpiresIn
+        });
+    };
+
+//# sourceMappingURL=refresh-route.js.map

package/dist/lib/session/refresh-route.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/session/refresh-route.ts"],"sourcesContent":["import { SESSION_COOKIE } from '@entifix/core';\nimport { type NextRequest, NextResponse } from 'next/server';\n\nimport { applySessionCookies, clearSessionCookies } from './cookies.js';\n\n/** The subset of auth-service's refresh response this handler needs. */\ninterface RefreshPayload {\n  readonly accessToken: string;\n  readonly expiresIn: number;\n  readonly sessionExpiresIn: number;\n}\n\nexport interface RefreshRouteOptions {\n  /** auth-service base URL; defaults to `AUTH_SERVICE_URL` then :3102. */\n  readonly authServiceUrl?: string;\n}\n\n/**\n * In-flight refreshes, keyed by session id.\n *\n * Several tabs and a lazy server-side refresh can all notice an expiring token\n * within the same second. Collapsing them costs one map and saves the round\n * trips. It is deliberately per-process and not the Redis `LockService`: session\n * ids do not rotate, so the worst a lost race can do is mint a second, equally\n * valid token — a wasted signature, not a correctness problem.\n */\nconst inFlight = new Map<string, Promise<Response>>();\n\nconst refreshOnce = (\n  authServiceUrl: string,\n  sessionId: string,\n): Promise<Response> => {\n  const existing = inFlight.get(sessionId);\n  if (existing !== undefined) return existing;\n\n  const pending = fetch(`${authServiceUrl}/api/auth/refresh`, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({ sessionId }),\n    cache: 'no-store',\n  }).finally(() => {\n    inFlight.delete(sessionId);\n  });\n\n  inFlight.set(sessionId, pending);\n  return pending;\n};\n\n/**\n * Builds `POST /api/auth/refresh` for an `-app`.\n *\n * Every app needs its own copy of this route because cookies are per-origin: in\n * production each `-app` is a different host and mints its own, and only\n * localhost's shared hostname makes it look otherwise. So the *handler* is\n * shared from here and each app mounts it.\n *\n * A dead session clears the cookies rather than leaving them to rot — otherwise\n * the browser keeps presenting a session id that will never refresh again, and\n * the middleware keeps believing there is a session to protect.\n */\nexport const createRefreshRoute =\n  (options: RefreshRouteOptions = {}) =>\n  async (request: NextRequest): Promise<NextResponse> => {\n    const authServiceUrl =\n      options.authServiceUrl ??\n      process.env.AUTH_SERVICE_URL ??\n      'http://localhost:3102';\n\n    const sessionId = request.cookies.get(SESSION_COOKIE)?.value;\n    if (sessionId === undefined) {\n      return NextResponse.json(\n        { error: 'no session', code: 'unauthenticated' },\n        { status: 401 },\n      );\n    }\n\n    const upstream = await refreshOnce(authServiceUrl, sessionId).catch(\n      () => undefined,\n    );\n    if (upstream === undefined) {\n      // The service is unreachable. The session may well still be fine, so the\n      // cookies stay and the client is told to retry rather than sign out.\n      return NextResponse.json(\n        { error: 'auth service unreachable', code: 'network' },\n        { status: 503 },\n      );\n    }\n\n    // `clone()` because a collapsed refresh hands the same Response to every\n    // waiter, and a body can only be read once.\n    const data = await upstream.clone().json();\n\n    if (!upstream.ok) {\n      return clearSessionCookies(\n        NextResponse.json(data, { status: upstream.status }),\n      );\n    }\n\n    const payload = data as RefreshPayload;\n    return applySessionCookies(\n      NextResponse.json({\n        ok: true,\n        expiresIn: payload.expiresIn,\n        sessionExpiresIn: payload.sessionExpiresIn,\n      }),\n      {\n        accessToken: payload.accessToken,\n        sessionExpiresIn: payload.sessionExpiresIn,\n      },\n    );\n  };\n"],"names":["SESSION_COOKIE","NextResponse","applySessionCookies","clearSessionCookies","inFlight","Map","refreshOnce","authServiceUrl","sessionId","existing","get","undefined","pending","fetch","method","headers","body","JSON","stringify","cache","finally","delete","set","createRefreshRoute","options","request","process","env","AUTH_SERVICE_URL","cookies","value","json","error","code","status","upstream","catch","data","clone","ok","payload","expiresIn","sessionExpiresIn","accessToken"],"mappings":"AAAA,SAASA,cAAc,QAAQ,gBAAgB;AAC/C,SAA2BC,YAAY,QAAQ,cAAc;AAE7D,SAASC,mBAAmB,EAAEC,mBAAmB,QAAQ,eAAe;AAcxE;;;;;;;;CAQC,GACD,MAAMC,WAAW,IAAIC;AAErB,MAAMC,cAAc,CAClBC,gBACAC;IAEA,MAAMC,WAAWL,SAASM,GAAG,CAACF;IAC9B,IAAIC,aAAaE,WAAW,OAAOF;IAEnC,MAAMG,UAAUC,MAAM,GAAGN,eAAe,iBAAiB,CAAC,EAAE;QAC1DO,QAAQ;QACRC,SAAS;YAAE,gBAAgB;QAAmB;QAC9CC,MAAMC,KAAKC,SAAS,CAAC;YAAEV;QAAU;QACjCW,OAAO;IACT,GAAGC,OAAO,CAAC;QACThB,SAASiB,MAAM,CAACb;IAClB;IAEAJ,SAASkB,GAAG,CAACd,WAAWI;IACxB,OAAOA;AACT;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,MAAMW,qBACX,CAACC,UAA+B,CAAC,CAAC,GAClC,OAAOC;YAEHD,MAAAA;YAIgBC;QALlB,MAAMlB,kBACJiB,QAAAA,0BAAAA,QAAQjB,cAAc,YAAtBiB,0BACAE,QAAQC,GAAG,CAACC,gBAAgB,YAD5BJ,OAEA;QAEF,MAAMhB,aAAYiB,uBAAAA,QAAQI,OAAO,CAACnB,GAAG,CAACV,oCAApByB,qBAAqCK,KAAK;QAC5D,IAAItB,cAAcG,WAAW;YAC3B,OAAOV,aAAa8B,IAAI,CACtB;gBAAEC,OAAO;gBAAcC,MAAM;YAAkB,GAC/C;gBAAEC,QAAQ;YAAI;QAElB;QAEA,MAAMC,WAAW,MAAM7B,YAAYC,gBAAgBC,WAAW4B,KAAK,CACjE,IAAMzB;QAER,IAAIwB,aAAaxB,WAAW;YAC1B,yEAAyE;YACzE,qEAAqE;YACrE,OAAOV,aAAa8B,IAAI,CACtB;gBAAEC,OAAO;gBAA4BC,MAAM;YAAU,GACrD;gBAAEC,QAAQ;YAAI;QAElB;QAEA,yEAAyE;QACzE,4CAA4C;QAC5C,MAAMG,OAAO,MAAMF,SAASG,KAAK,GAAGP,IAAI;QAExC,IAAI,CAACI,SAASI,EAAE,EAAE;YAChB,OAAOpC,oBACLF,aAAa8B,IAAI,CAACM,MAAM;gBAAEH,QAAQC,SAASD,MAAM;YAAC;QAEtD;QAEA,MAAMM,UAAUH;QAChB,OAAOnC,oBACLD,aAAa8B,IAAI,CAAC;YAChBQ,IAAI;YACJE,WAAWD,QAAQC,SAAS;YAC5BC,kBAAkBF,QAAQE,gBAAgB;QAC5C,IACA;YACEC,aAAaH,QAAQG,WAAW;YAChCD,kBAAkBF,QAAQE,gBAAgB;QAC5C;IAEJ,EAAE"}

package/dist/lib/session/session-keepalive.d.ts

@@ -0,0 +1,52 @@
+export interface SessionKeepaliveProps {
+    /** Where this app mounts the shared refresh handler. */
+    readonly endpoint?: string;
+    /**
+     * What to do when the session is over. Defaults to reloading the page, which
+     * is almost always the right answer — see the note on {@link
+     * SessionKeepalive}.
+     */
+    readonly onExpired?: () => void;
+}
+/**
+ * Mounts {@link useSessionRefresh} and acts on what it reports.
+ *
+ * ⚠️ **This component is why the hook does anything at all.** The hook shipped
+ * with its schedule, its idle gate, its countdown and a full spec, and was
+ * referenced by nothing — no app, no shell, no layout. So no browser in the
+ * fleet ever posted to `/api/auth/refresh`, and three separately reasonable
+ * facts combined into a bug (#252): the access token lives 15 minutes, both
+ * cookies are sized to the seven-day session ceiling so that a cookie does not
+ * sign everyone out every 15 minutes, and the middleware can only check that a
+ * cookie is *present* because the edge cannot verify a signature. The visitor
+ * was therefore admitted to pages that rendered fine while every call behind
+ * them answered `401`.
+ *
+ * **Expiry reloads rather than routing anywhere**, and that is the smaller
+ * change rather than the lazier one. By the time the hook reports `expired` the
+ * refresh route has already cleared both cookies — a dead session clears them
+ * instead of leaving the browser presenting a session id that will never
+ * refresh again. A reload then meets the middleware with no cookie, and the
+ * middleware redirects to sign-in with the right locale and the right
+ * `redirect` parameter. Building that URL here would be a second copy of a rule
+ * that already exists, and the two would drift the first time either changed.
+ *
+ * A form's unsaved work survives it, because a workspace draft is autosaved to
+ * IndexedDB rather than held in the page
+ * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).
+ *
+ * Renders nothing but a warning strip, and only inside the final window before
+ * the ceiling. `role="status"` rather than `role="alert"`: the session ending
+ * soon is a thing to notice, not an error to interrupt for, and an assertive
+ * live region would talk over whatever the person is actually doing.
+ *
+ * Neutral surface tokens rather than a warning colour, because the contract has
+ * no warning colour — it carries `danger` and its subtle and content pair, and
+ * nothing between that and the neutrals. Borrowing `danger` for "your session
+ * ends in five minutes" would spend the one alarming colour on something that is
+ * not an error; adding a semantic colour is a change to the token contract
+ * ([ADR 0027](../../../../../../docs/adr/0027-two-scales-a-density-mode-and-the-type-system.md))
+ * and does not belong in a session fix.
+ */
+export declare function SessionKeepalive({ endpoint, onExpired, }?: SessionKeepaliveProps): import("react").JSX.Element | null;
+//# sourceMappingURL=session-keepalive.d.ts.map

package/dist/lib/session/session-keepalive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-keepalive.d.ts","sourceRoot":"","sources":["../../../src/lib/session/session-keepalive.tsx"],"names":[],"mappings":"AAOA,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,GACV,GAAE,qBAA0B,sCA6B5B"}

package/dist/lib/session/session-keepalive.js

@@ -0,0 +1,72 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useT } from '@entifix/react-controls';
+import { useCallback } from 'react';
+import { useSessionRefresh } from './use-session-refresh.js';
+/**
+ * Mounts {@link useSessionRefresh} and acts on what it reports.
+ *
+ * ⚠️ **This component is why the hook does anything at all.** The hook shipped
+ * with its schedule, its idle gate, its countdown and a full spec, and was
+ * referenced by nothing — no app, no shell, no layout. So no browser in the
+ * fleet ever posted to `/api/auth/refresh`, and three separately reasonable
+ * facts combined into a bug (#252): the access token lives 15 minutes, both
+ * cookies are sized to the seven-day session ceiling so that a cookie does not
+ * sign everyone out every 15 minutes, and the middleware can only check that a
+ * cookie is *present* because the edge cannot verify a signature. The visitor
+ * was therefore admitted to pages that rendered fine while every call behind
+ * them answered `401`.
+ *
+ * **Expiry reloads rather than routing anywhere**, and that is the smaller
+ * change rather than the lazier one. By the time the hook reports `expired` the
+ * refresh route has already cleared both cookies — a dead session clears them
+ * instead of leaving the browser presenting a session id that will never
+ * refresh again. A reload then meets the middleware with no cookie, and the
+ * middleware redirects to sign-in with the right locale and the right
+ * `redirect` parameter. Building that URL here would be a second copy of a rule
+ * that already exists, and the two would drift the first time either changed.
+ *
+ * A form's unsaved work survives it, because a workspace draft is autosaved to
+ * IndexedDB rather than held in the page
+ * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).
+ *
+ * Renders nothing but a warning strip, and only inside the final window before
+ * the ceiling. `role="status"` rather than `role="alert"`: the session ending
+ * soon is a thing to notice, not an error to interrupt for, and an assertive
+ * live region would talk over whatever the person is actually doing.
+ *
+ * Neutral surface tokens rather than a warning colour, because the contract has
+ * no warning colour — it carries `danger` and its subtle and content pair, and
+ * nothing between that and the neutrals. Borrowing `danger` for "your session
+ * ends in five minutes" would spend the one alarming colour on something that is
+ * not an error; adding a semantic colour is a change to the token contract
+ * ([ADR 0027](../../../../../../docs/adr/0027-two-scales-a-density-mode-and-the-type-system.md))
+ * and does not belong in a session fix.
+ */ export function SessionKeepalive({ endpoint, onExpired } = {}) {
+    // A reload rather than a route change: middleware is what knows where a
+    // signed-out visitor goes, and `router.push` would keep the dead client-side
+    // tree around while it got there.
+    const expire = useCallback(()=>{
+        if (onExpired) {
+            onExpired();
+            return;
+        }
+        window.location.reload();
+    }, [
+        onExpired
+    ]);
+    const { expiringSoon, expired } = useSessionRefresh({
+        endpoint,
+        onExpired: expire
+    });
+    const t = useT('shell');
+    if (expired || !expiringSoon) return null;
+    return /*#__PURE__*/ _jsx("div", {
+        role: "status",
+        "data-testid": "session-expiring",
+        className: "border-b border-border bg-surface-elevated px-s py-2xs text-step-sm text-content",
+        children: t('session.expiringSoon')
+    });
+}
+
+//# sourceMappingURL=session-keepalive.js.map

package/dist/lib/session/session-keepalive.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/session/session-keepalive.tsx"],"sourcesContent":["'use client';\n\nimport { useT } from '@entifix/react-controls';\nimport { useCallback } from 'react';\n\nimport { useSessionRefresh } from './use-session-refresh.js';\n\nexport interface SessionKeepaliveProps {\n  /** Where this app mounts the shared refresh handler. */\n  readonly endpoint?: string;\n  /**\n   * What to do when the session is over. Defaults to reloading the page, which\n   * is almost always the right answer — see the note on {@link\n   * SessionKeepalive}.\n   */\n  readonly onExpired?: () => void;\n}\n\n/**\n * Mounts {@link useSessionRefresh} and acts on what it reports.\n *\n * ⚠️ **This component is why the hook does anything at all.** The hook shipped\n * with its schedule, its idle gate, its countdown and a full spec, and was\n * referenced by nothing — no app, no shell, no layout. So no browser in the\n * fleet ever posted to `/api/auth/refresh`, and three separately reasonable\n * facts combined into a bug (#252): the access token lives 15 minutes, both\n * cookies are sized to the seven-day session ceiling so that a cookie does not\n * sign everyone out every 15 minutes, and the middleware can only check that a\n * cookie is *present* because the edge cannot verify a signature. The visitor\n * was therefore admitted to pages that rendered fine while every call behind\n * them answered `401`.\n *\n * **Expiry reloads rather than routing anywhere**, and that is the smaller\n * change rather than the lazier one. By the time the hook reports `expired` the\n * refresh route has already cleared both cookies — a dead session clears them\n * instead of leaving the browser presenting a session id that will never\n * refresh again. A reload then meets the middleware with no cookie, and the\n * middleware redirects to sign-in with the right locale and the right\n * `redirect` parameter. Building that URL here would be a second copy of a rule\n * that already exists, and the two would drift the first time either changed.\n *\n * A form's unsaved work survives it, because a workspace draft is autosaved to\n * IndexedDB rather than held in the page\n * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).\n *\n * Renders nothing but a warning strip, and only inside the final window before\n * the ceiling. `role=\"status\"` rather than `role=\"alert\"`: the session ending\n * soon is a thing to notice, not an error to interrupt for, and an assertive\n * live region would talk over whatever the person is actually doing.\n *\n * Neutral surface tokens rather than a warning colour, because the contract has\n * no warning colour — it carries `danger` and its subtle and content pair, and\n * nothing between that and the neutrals. Borrowing `danger` for \"your session\n * ends in five minutes\" would spend the one alarming colour on something that is\n * not an error; adding a semantic colour is a change to the token contract\n * ([ADR 0027](../../../../../../docs/adr/0027-two-scales-a-density-mode-and-the-type-system.md))\n * and does not belong in a session fix.\n */\nexport function SessionKeepalive({\n  endpoint,\n  onExpired,\n}: SessionKeepaliveProps = {}) {\n  // A reload rather than a route change: middleware is what knows where a\n  // signed-out visitor goes, and `router.push` would keep the dead client-side\n  // tree around while it got there.\n  const expire = useCallback(() => {\n    if (onExpired) {\n      onExpired();\n      return;\n    }\n    window.location.reload();\n  }, [onExpired]);\n\n  const { expiringSoon, expired } = useSessionRefresh({\n    endpoint,\n    onExpired: expire,\n  });\n  const t = useT('shell');\n\n  if (expired || !expiringSoon) return null;\n\n  return (\n    <div\n      role=\"status\"\n      data-testid=\"session-expiring\"\n      className=\"border-b border-border bg-surface-elevated px-s py-2xs text-step-sm text-content\"\n    >\n      {t('session.expiringSoon')}\n    </div>\n  );\n}\n"],"names":["useT","useCallback","useSessionRefresh","SessionKeepalive","endpoint","onExpired","expire","window","location","reload","expiringSoon","expired","t","div","role","data-testid","className"],"mappings":"AAAA;;AAEA,SAASA,IAAI,QAAQ,0BAA0B;AAC/C,SAASC,WAAW,QAAQ,QAAQ;AAEpC,SAASC,iBAAiB,QAAQ,2BAA2B;AAa7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GACD,OAAO,SAASC,iBAAiB,EAC/BC,QAAQ,EACRC,SAAS,EACa,GAAG,CAAC,CAAC;IAC3B,wEAAwE;IACxE,6EAA6E;IAC7E,kCAAkC;IAClC,MAAMC,SAASL,YAAY;QACzB,IAAII,WAAW;YACbA;YACA;QACF;QACAE,OAAOC,QAAQ,CAACC,MAAM;IACxB,GAAG;QAACJ;KAAU;IAEd,MAAM,EAAEK,YAAY,EAAEC,OAAO,EAAE,GAAGT,kBAAkB;QAClDE;QACAC,WAAWC;IACb;IACA,MAAMM,IAAIZ,KAAK;IAEf,IAAIW,WAAW,CAACD,cAAc,OAAO;IAErC,qBACE,KAACG;QACCC,MAAK;QACLC,eAAY;QACZC,WAAU;kBAETJ,EAAE;;AAGT"}

package/dist/lib/session/use-session-refresh.d.ts

@@ -0,0 +1,43 @@
+export interface UseSessionRefreshOptions {
+    /** Where this app mounts the shared refresh handler. */
+    readonly endpoint?: string;
+    /** Access-token lifetime in seconds; the schedule derives from it. */
+    readonly tokenTtlSeconds?: number;
+    /**
+     * How long without interaction before the timer stops asking.
+     *
+     * This is what makes "idle timeout" measure whether a person is there rather
+     * than whether a tab is open, so a host raising it is choosing to keep
+     * forgotten tabs alive.
+     */
+    readonly idleStopSeconds?: number;
+    /** How long before the absolute ceiling `expiringSoon` turns true. */
+    readonly expiryWarningSeconds?: number;
+    /** Fraction of the token's life at which to refresh. */
+    readonly refreshLeadRatio?: number;
+    /** Called when the session is gone and the user has to sign in again. */
+    readonly onExpired?: () => void;
+}
+export interface SessionRefreshState {
+    /** Seconds left before the session's absolute ceiling, once known. */
+    readonly sessionExpiresIn: number | undefined;
+    /** True inside the final window before the ceiling — prompt the user. */
+    readonly expiringSoon: boolean;
+    /** True once a refresh has failed and the session is over. */
+    readonly expired: boolean;
+}
+/**
+ * Keeps the access-token cookie fresh while someone is actually using the app.
+ *
+ * The refresh runs on a timer at 80% of the token's life, but **only while the
+ * user has interacted recently**. That condition is the whole point: the server
+ * slides the session on refresh, so a timer that fired unconditionally would
+ * keep a forgotten tab's session alive forever and "idle timeout" would measure
+ * whether a tab is open rather than whether a person is there. Going quiet lets
+ * the token lapse and the session age out on schedule.
+ *
+ * The token itself is never visible here — it lives in an httpOnly cookie, and
+ * the endpoint below rewrites it server-side.
+ */
+export declare function useSessionRefresh(options?: UseSessionRefreshOptions): SessionRefreshState;
+//# sourceMappingURL=use-session-refresh.d.ts.map

package/dist/lib/session/use-session-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-session-refresh.d.ts","sourceRoot":"","sources":["../../../src/lib/session/use-session-refresh.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,mBAAmB,CAiGrB"}

package/dist/lib/session/use-session-refresh.js

@@ -0,0 +1,120 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** Browser events that count as a person being present. */ const ACTIVITY_EVENTS = [
+    'pointerdown',
+    'keydown',
+    'scroll',
+    'visibilitychange'
+];
+/**
+ * Session timing, as this shell assumes it when a host says nothing.
+ *
+ * ⚠️ **Defaults, not policy.** These four used to be imported from the
+ * application's own session package, which made a framework hook carry one
+ * product's security decisions — and meant a second application could not use
+ * the hook at all without adopting r10c's token lifetime. A host that has a
+ * session policy passes it in; a host that has not yet thought about it gets
+ * numbers that are defensible rather than absent.
+ *
+ * The server is still the authority. These only decide when the browser *asks*;
+ * the refresh endpoint decides whether the session actually slides.
+ */ const DEFAULT_TOKEN_TTL_SECONDS = 60 * 15;
+const DEFAULT_IDLE_STOP_SECONDS = 60 * 15;
+const DEFAULT_EXPIRY_WARNING_SECONDS = 60 * 5;
+const DEFAULT_REFRESH_LEAD_RATIO = 0.8;
+/**
+ * Keeps the access-token cookie fresh while someone is actually using the app.
+ *
+ * The refresh runs on a timer at 80% of the token's life, but **only while the
+ * user has interacted recently**. That condition is the whole point: the server
+ * slides the session on refresh, so a timer that fired unconditionally would
+ * keep a forgotten tab's session alive forever and "idle timeout" would measure
+ * whether a tab is open rather than whether a person is there. Going quiet lets
+ * the token lapse and the session age out on schedule.
+ *
+ * The token itself is never visible here — it lives in an httpOnly cookie, and
+ * the endpoint below rewrites it server-side.
+ */ export function useSessionRefresh(options = {}) {
+    const { endpoint = '/api/auth/refresh', tokenTtlSeconds = DEFAULT_TOKEN_TTL_SECONDS, idleStopSeconds = DEFAULT_IDLE_STOP_SECONDS, expiryWarningSeconds = DEFAULT_EXPIRY_WARNING_SECONDS, refreshLeadRatio = DEFAULT_REFRESH_LEAD_RATIO, onExpired } = options;
+    const [sessionExpiresIn, setSessionExpiresIn] = useState(undefined);
+    const [expired, setExpired] = useState(false);
+    // Seeded on mount rather than at construction: reading the clock during
+    // render is impure, and the value is only ever consumed from an effect.
+    const lastActivity = useRef(0);
+    const onExpiredRef = useRef(onExpired);
+    /**
+   * Mirrors `expired` synchronously. The state update only tears the interval
+   * down on the next render, so without this a burst of ticks fires — and
+   * `onExpired` runs — several times over for one dead session.
+   */ const expiredRef = useRef(false);
+    useEffect(()=>{
+        onExpiredRef.current = onExpired;
+    }, [
+        onExpired
+    ]);
+    const markActive = useCallback(()=>{
+        lastActivity.current = Date.now();
+    }, []);
+    useEffect(()=>{
+        markActive();
+        for (const event of ACTIVITY_EVENTS){
+            window.addEventListener(event, markActive, {
+                passive: true
+            });
+        }
+        return ()=>{
+            for (const event of ACTIVITY_EVENTS){
+                window.removeEventListener(event, markActive);
+            }
+        };
+    }, [
+        markActive
+    ]);
+    useEffect(()=>{
+        if (expired) return undefined;
+        const periodMs = Math.max(1, Math.floor(tokenTtlSeconds * refreshLeadRatio)) * 1000;
+        let cancelled = false;
+        const tick = async ()=>{
+            if (expiredRef.current) return;
+            const idleFor = (Date.now() - lastActivity.current) / 1000;
+            // Nobody is here. Skipping the refresh is what lets the session lapse.
+            if (idleFor > idleStopSeconds) return;
+            try {
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    cache: 'no-store'
+                });
+                if (cancelled) return;
+                if (response.status === 401) {
+                    expiredRef.current = true;
+                    setExpired(true);
+                    onExpiredRef.current == null ? void 0 : onExpiredRef.current.call(onExpiredRef);
+                    return;
+                }
+                if (!response.ok) return; // transient (503) — try again next tick
+                const body = await response.json();
+                if (!cancelled && typeof body.sessionExpiresIn === 'number') {
+                    setSessionExpiresIn(body.sessionExpiresIn);
+                }
+            } catch (unused) {
+            // Offline or a dropped request: keep the schedule and retry.
+            }
+        };
+        const timer = setInterval(tick, periodMs);
+        return ()=>{
+            cancelled = true;
+            clearInterval(timer);
+        };
+    }, [
+        endpoint,
+        tokenTtlSeconds,
+        expired
+    ]);
+    return {
+        sessionExpiresIn,
+        expiringSoon: sessionExpiresIn !== undefined && sessionExpiresIn <= expiryWarningSeconds,
+        expired
+    };
+}
+
+//# sourceMappingURL=use-session-refresh.js.map

package/dist/lib/session/use-session-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/session/use-session-refresh.ts"],"sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\n/** Browser events that count as a person being present. */\nconst ACTIVITY_EVENTS = [\n  'pointerdown',\n  'keydown',\n  'scroll',\n  'visibilitychange',\n] as const;\n\n/**\n * Session timing, as this shell assumes it when a host says nothing.\n *\n * ⚠️ **Defaults, not policy.** These four used to be imported from the\n * application's own session package, which made a framework hook carry one\n * product's security decisions — and meant a second application could not use\n * the hook at all without adopting r10c's token lifetime. A host that has a\n * session policy passes it in; a host that has not yet thought about it gets\n * numbers that are defensible rather than absent.\n *\n * The server is still the authority. These only decide when the browser *asks*;\n * the refresh endpoint decides whether the session actually slides.\n */\nconst DEFAULT_TOKEN_TTL_SECONDS = 60 * 15;\nconst DEFAULT_IDLE_STOP_SECONDS = 60 * 15;\nconst DEFAULT_EXPIRY_WARNING_SECONDS = 60 * 5;\nconst DEFAULT_REFRESH_LEAD_RATIO = 0.8;\n\nexport interface UseSessionRefreshOptions {\n  /** Where this app mounts the shared refresh handler. */\n  readonly endpoint?: string;\n  /** Access-token lifetime in seconds; the schedule derives from it. */\n  readonly tokenTtlSeconds?: number;\n  /**\n   * How long without interaction before the timer stops asking.\n   *\n   * This is what makes \"idle timeout\" measure whether a person is there rather\n   * than whether a tab is open, so a host raising it is choosing to keep\n   * forgotten tabs alive.\n   */\n  readonly idleStopSeconds?: number;\n  /** How long before the absolute ceiling `expiringSoon` turns true. */\n  readonly expiryWarningSeconds?: number;\n  /** Fraction of the token's life at which to refresh. */\n  readonly refreshLeadRatio?: number;\n  /** Called when the session is gone and the user has to sign in again. */\n  readonly onExpired?: () => void;\n}\n\nexport interface SessionRefreshState {\n  /** Seconds left before the session's absolute ceiling, once known. */\n  readonly sessionExpiresIn: number | undefined;\n  /** True inside the final window before the ceiling — prompt the user. */\n  readonly expiringSoon: boolean;\n  /** True once a refresh has failed and the session is over. */\n  readonly expired: boolean;\n}\n\n/**\n * Keeps the access-token cookie fresh while someone is actually using the app.\n *\n * The refresh runs on a timer at 80% of the token's life, but **only while the\n * user has interacted recently**. That condition is the whole point: the server\n * slides the session on refresh, so a timer that fired unconditionally would\n * keep a forgotten tab's session alive forever and \"idle timeout\" would measure\n * whether a tab is open rather than whether a person is there. Going quiet lets\n * the token lapse and the session age out on schedule.\n *\n * The token itself is never visible here — it lives in an httpOnly cookie, and\n * the endpoint below rewrites it server-side.\n */\nexport function useSessionRefresh(\n  options: UseSessionRefreshOptions = {},\n): SessionRefreshState {\n  const {\n    endpoint = '/api/auth/refresh',\n    tokenTtlSeconds = DEFAULT_TOKEN_TTL_SECONDS,\n    idleStopSeconds = DEFAULT_IDLE_STOP_SECONDS,\n    expiryWarningSeconds = DEFAULT_EXPIRY_WARNING_SECONDS,\n    refreshLeadRatio = DEFAULT_REFRESH_LEAD_RATIO,\n    onExpired,\n  } = options;\n\n  const [sessionExpiresIn, setSessionExpiresIn] = useState<number | undefined>(\n    undefined,\n  );\n  const [expired, setExpired] = useState(false);\n  // Seeded on mount rather than at construction: reading the clock during\n  // render is impure, and the value is only ever consumed from an effect.\n  const lastActivity = useRef(0);\n  const onExpiredRef = useRef(onExpired);\n  /**\n   * Mirrors `expired` synchronously. The state update only tears the interval\n   * down on the next render, so without this a burst of ticks fires — and\n   * `onExpired` runs — several times over for one dead session.\n   */\n  const expiredRef = useRef(false);\n\n  useEffect(() => {\n    onExpiredRef.current = onExpired;\n  }, [onExpired]);\n\n  const markActive = useCallback(() => {\n    lastActivity.current = Date.now();\n  }, []);\n\n  useEffect(() => {\n    markActive();\n    for (const event of ACTIVITY_EVENTS) {\n      window.addEventListener(event, markActive, { passive: true });\n    }\n    return () => {\n      for (const event of ACTIVITY_EVENTS) {\n        window.removeEventListener(event, markActive);\n      }\n    };\n  }, [markActive]);\n\n  useEffect(() => {\n    if (expired) return undefined;\n\n    const periodMs =\n      Math.max(1, Math.floor(tokenTtlSeconds * refreshLeadRatio)) * 1000;\n    let cancelled = false;\n\n    const tick = async () => {\n      if (expiredRef.current) return;\n\n      const idleFor = (Date.now() - lastActivity.current) / 1000;\n      // Nobody is here. Skipping the refresh is what lets the session lapse.\n      if (idleFor > idleStopSeconds) return;\n\n      try {\n        const response = await fetch(endpoint, {\n          method: 'POST',\n          cache: 'no-store',\n        });\n        if (cancelled) return;\n\n        if (response.status === 401) {\n          expiredRef.current = true;\n          setExpired(true);\n          onExpiredRef.current?.();\n          return;\n        }\n        if (!response.ok) return; // transient (503) — try again next tick\n\n        const body = (await response.json()) as { sessionExpiresIn?: number };\n        if (!cancelled && typeof body.sessionExpiresIn === 'number') {\n          setSessionExpiresIn(body.sessionExpiresIn);\n        }\n      } catch {\n        // Offline or a dropped request: keep the schedule and retry.\n      }\n    };\n\n    const timer = setInterval(tick, periodMs);\n    return () => {\n      cancelled = true;\n      clearInterval(timer);\n    };\n  }, [endpoint, tokenTtlSeconds, expired]);\n\n  return {\n    sessionExpiresIn,\n    expiringSoon:\n      sessionExpiresIn !== undefined &&\n      sessionExpiresIn <= expiryWarningSeconds,\n    expired,\n  };\n}\n"],"names":["useCallback","useEffect","useRef","useState","ACTIVITY_EVENTS","DEFAULT_TOKEN_TTL_SECONDS","DEFAULT_IDLE_STOP_SECONDS","DEFAULT_EXPIRY_WARNING_SECONDS","DEFAULT_REFRESH_LEAD_RATIO","useSessionRefresh","options","endpoint","tokenTtlSeconds","idleStopSeconds","expiryWarningSeconds","refreshLeadRatio","onExpired","sessionExpiresIn","setSessionExpiresIn","undefined","expired","setExpired","lastActivity","onExpiredRef","expiredRef","current","markActive","Date","now","event","window","addEventListener","passive","removeEventListener","periodMs","Math","max","floor","cancelled","tick","idleFor","response","fetch","method","cache","status","ok","body","json","timer","setInterval","clearInterval","expiringSoon"],"mappings":"AAAA;AAEA,SAASA,WAAW,EAAEC,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,QAAQ;AAEjE,yDAAyD,GACzD,MAAMC,kBAAkB;IACtB;IACA;IACA;IACA;CACD;AAED;;;;;;;;;;;;CAYC,GACD,MAAMC,4BAA4B,KAAK;AACvC,MAAMC,4BAA4B,KAAK;AACvC,MAAMC,iCAAiC,KAAK;AAC5C,MAAMC,6BAA6B;AAgCnC;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,kBACdC,UAAoC,CAAC,CAAC;IAEtC,MAAM,EACJC,WAAW,mBAAmB,EAC9BC,kBAAkBP,yBAAyB,EAC3CQ,kBAAkBP,yBAAyB,EAC3CQ,uBAAuBP,8BAA8B,EACrDQ,mBAAmBP,0BAA0B,EAC7CQ,SAAS,EACV,GAAGN;IAEJ,MAAM,CAACO,kBAAkBC,oBAAoB,GAAGf,SAC9CgB;IAEF,MAAM,CAACC,SAASC,WAAW,GAAGlB,SAAS;IACvC,wEAAwE;IACxE,wEAAwE;IACxE,MAAMmB,eAAepB,OAAO;IAC5B,MAAMqB,eAAerB,OAAOc;IAC5B;;;;GAIC,GACD,MAAMQ,aAAatB,OAAO;IAE1BD,UAAU;QACRsB,aAAaE,OAAO,GAAGT;IACzB,GAAG;QAACA;KAAU;IAEd,MAAMU,aAAa1B,YAAY;QAC7BsB,aAAaG,OAAO,GAAGE,KAAKC,GAAG;IACjC,GAAG,EAAE;IAEL3B,UAAU;QACRyB;QACA,KAAK,MAAMG,SAASzB,gBAAiB;YACnC0B,OAAOC,gBAAgB,CAACF,OAAOH,YAAY;gBAAEM,SAAS;YAAK;QAC7D;QACA,OAAO;YACL,KAAK,MAAMH,SAASzB,gBAAiB;gBACnC0B,OAAOG,mBAAmB,CAACJ,OAAOH;YACpC;QACF;IACF,GAAG;QAACA;KAAW;IAEfzB,UAAU;QACR,IAAImB,SAAS,OAAOD;QAEpB,MAAMe,WACJC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,KAAK,CAACzB,kBAAkBG,qBAAqB;QAChE,IAAIuB,YAAY;QAEhB,MAAMC,OAAO;YACX,IAAIf,WAAWC,OAAO,EAAE;YAExB,MAAMe,UAAU,AAACb,CAAAA,KAAKC,GAAG,KAAKN,aAAaG,OAAO,AAAD,IAAK;YACtD,uEAAuE;YACvE,IAAIe,UAAU3B,iBAAiB;YAE/B,IAAI;gBACF,MAAM4B,WAAW,MAAMC,MAAM/B,UAAU;oBACrCgC,QAAQ;oBACRC,OAAO;gBACT;gBACA,IAAIN,WAAW;gBAEf,IAAIG,SAASI,MAAM,KAAK,KAAK;oBAC3BrB,WAAWC,OAAO,GAAG;oBACrBJ,WAAW;oBACXE,aAAaE,OAAO,oBAApBF,aAAaE,OAAO,MAApBF;oBACA;gBACF;gBACA,IAAI,CAACkB,SAASK,EAAE,EAAE,QAAQ,wCAAwC;gBAElE,MAAMC,OAAQ,MAAMN,SAASO,IAAI;gBACjC,IAAI,CAACV,aAAa,OAAOS,KAAK9B,gBAAgB,KAAK,UAAU;oBAC3DC,oBAAoB6B,KAAK9B,gBAAgB;gBAC3C;YACF,EAAE,eAAM;YACN,6DAA6D;YAC/D;QACF;QAEA,MAAMgC,QAAQC,YAAYX,MAAML;QAChC,OAAO;YACLI,YAAY;YACZa,cAAcF;QAChB;IACF,GAAG;QAACtC;QAAUC;QAAiBQ;KAAQ;IAEvC,OAAO;QACLH;QACAmC,cACEnC,qBAAqBE,aACrBF,oBAAoBH;QACtBM;IACF;AACF"}

package/dist/lib/wizard/index.d.ts

@@ -0,0 +1,4 @@
+export * from './use-wizard-draft.js';
+export * from './use-wizard-step-param.js';
+export * from './wizard-tab-kind.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/wizard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/wizard/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/dist/lib/wizard/index.js

@@ -0,0 +1,5 @@
+export * from './use-wizard-draft.js';
+export * from './use-wizard-step-param.js';
+export * from './wizard-tab-kind.js';
+
+//# sourceMappingURL=index.js.map

package/dist/lib/wizard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/wizard/index.ts"],"sourcesContent":["export * from './use-wizard-draft.js';\nexport * from './use-wizard-step-param.js';\nexport * from './wizard-tab-kind.js';\n"],"names":[],"mappings":"AAAA,cAAc,wBAAwB;AACtC,cAAc,6BAA6B;AAC3C,cAAc,uBAAuB"}

package/dist/lib/wizard/use-wizard-draft.d.ts

@@ -0,0 +1,22 @@
+import type { WizardDraftStore } from '@entifix/react-integration';
+/**
+ * The workspace's implementation of `useWizard`'s draft port: binds a wizard to
+ * the address-keyed state this workspace persists to IndexedDB.
+ *
+ * The sibling of `useEntityDraft`, and deliberately a second hook rather than a
+ * widening of it: the two persist different shapes — one an `EntityDraft`, this
+ * a whole `WizardState` — so one hook serving both would let a form be handed a
+ * wizard's state by a caller that mixed up the addresses.
+ *
+ * ⚠️ What comes back from storage is **narrowed**, not trusted. A stored wizard
+ * can be anything a previous build wrote, and a step whose shape no longer
+ * parses is answered with a fresh wizard rather than a crash — `readWizardState`
+ * makes that call, and it fails the whole state rather than dropping one step,
+ * because resuming with one page silently forgotten is worse than starting over.
+ *
+ * The returned object is memoised because the port requires a stable `save`: the
+ * hook writes from a handler keyed on it, so a fresh identity each render would
+ * turn every render into an IndexedDB write.
+ */
+export declare function useWizardDraft(address: string): WizardDraftStore;
+//# sourceMappingURL=use-wizard-draft.d.ts.map

package/dist/lib/wizard/use-wizard-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-wizard-draft.d.ts","sourceRoot":"","sources":["../../../src/lib/wizard/use-wizard-draft.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAKnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAShE"}

package/dist/lib/wizard/use-wizard-draft.js

@@ -0,0 +1,39 @@
+'use client';
+import { readWizardState } from '@entifix/core';
+import { useMemo } from 'react';
+import { useDraft } from '../workspace/drafts-state.js';
+/**
+ * The workspace's implementation of `useWizard`'s draft port: binds a wizard to
+ * the address-keyed state this workspace persists to IndexedDB.
+ *
+ * The sibling of `useEntityDraft`, and deliberately a second hook rather than a
+ * widening of it: the two persist different shapes — one an `EntityDraft`, this
+ * a whole `WizardState` — so one hook serving both would let a form be handed a
+ * wizard's state by a caller that mixed up the addresses.
+ *
+ * ⚠️ What comes back from storage is **narrowed**, not trusted. A stored wizard
+ * can be anything a previous build wrote, and a step whose shape no longer
+ * parses is answered with a fresh wizard rather than a crash — `readWizardState`
+ * makes that call, and it fails the whole state rather than dropping one step,
+ * because resuming with one page silently forgotten is worse than starting over.
+ *
+ * The returned object is memoised because the port requires a stable `save`: the
+ * hook writes from a handler keyed on it, so a fresh identity each render would
+ * turn every render into an IndexedDB write.
+ */ export function useWizardDraft(address) {
+    const { draft, setDraft, clearDraft } = useDraft(address);
+    const state = useMemo(()=>readWizardState(draft), [
+        draft
+    ]);
+    return useMemo(()=>({
+            state,
+            save: setDraft,
+            clear: clearDraft
+        }), [
+        state,
+        setDraft,
+        clearDraft
+    ]);
+}
+
+//# sourceMappingURL=use-wizard-draft.js.map

package/dist/lib/wizard/use-wizard-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/wizard/use-wizard-draft.ts"],"sourcesContent":["'use client';\n\nimport { readWizardState, type WizardState } from '@entifix/core';\nimport type { WizardDraftStore } from '@entifix/react-integration';\nimport { useMemo } from 'react';\n\nimport { useDraft } from '../workspace/drafts-state.js';\n\n/**\n * The workspace's implementation of `useWizard`'s draft port: binds a wizard to\n * the address-keyed state this workspace persists to IndexedDB.\n *\n * The sibling of `useEntityDraft`, and deliberately a second hook rather than a\n * widening of it: the two persist different shapes — one an `EntityDraft`, this\n * a whole `WizardState` — so one hook serving both would let a form be handed a\n * wizard's state by a caller that mixed up the addresses.\n *\n * ⚠️ What comes back from storage is **narrowed**, not trusted. A stored wizard\n * can be anything a previous build wrote, and a step whose shape no longer\n * parses is answered with a fresh wizard rather than a crash — `readWizardState`\n * makes that call, and it fails the whole state rather than dropping one step,\n * because resuming with one page silently forgotten is worse than starting over.\n *\n * The returned object is memoised because the port requires a stable `save`: the\n * hook writes from a handler keyed on it, so a fresh identity each render would\n * turn every render into an IndexedDB write.\n */\nexport function useWizardDraft(address: string): WizardDraftStore {\n  const { draft, setDraft, clearDraft } = useDraft<WizardState>(address);\n\n  const state = useMemo(() => readWizardState(draft), [draft]);\n\n  return useMemo(\n    () => ({ state, save: setDraft, clear: clearDraft }),\n    [state, setDraft, clearDraft],\n  );\n}\n"],"names":["readWizardState","useMemo","useDraft","useWizardDraft","address","draft","setDraft","clearDraft","state","save","clear"],"mappings":"AAAA;AAEA,SAASA,eAAe,QAA0B,gBAAgB;AAElE,SAASC,OAAO,QAAQ,QAAQ;AAEhC,SAASC,QAAQ,QAAQ,+BAA+B;AAExD;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,eAAeC,OAAe;IAC5C,MAAM,EAAEC,KAAK,EAAEC,QAAQ,EAAEC,UAAU,EAAE,GAAGL,SAAsBE;IAE9D,MAAMI,QAAQP,QAAQ,IAAMD,gBAAgBK,QAAQ;QAACA;KAAM;IAE3D,OAAOJ,QACL,IAAO,CAAA;YAAEO;YAAOC,MAAMH;YAAUI,OAAOH;QAAW,CAAA,GAClD;QAACC;QAAOF;QAAUC;KAAW;AAEjC"}

package/dist/lib/wizard/use-wizard-step-param.d.ts

@@ -0,0 +1,60 @@
+/** The query parameter a wizard route carries its step in. */
+export declare const WIZARD_STEP_PARAM = "step";
+/**
+ * Writes a step into the address — what `useWizard`'s `onStepChange` is wired to.
+ *
+ * ⚠️ **This must be handed to `useWizard` directly, never through a ref.** The
+ * push has to land in the same commit as the move: the follower below compares
+ * the address with the active step, so a report that arrives a tick late leaves
+ * the two disagreeing, and the follower reads that as a Back and moves the
+ * wizard *back* to the step it just left. Splitting the writer from the follower
+ * is what removes the cycle that made a ref look necessary.
+ *
+ * It **checks the address before pushing**, and that guard is what stops the
+ * loop: a Back drives `goTo`, which reports the move, which would otherwise push
+ * the very address Back had just restored — turning one press into an entry the
+ * operator has to get past twice.
+ */
+export declare function useWizardStepUrl(): (stepId: string) => void;
+export interface FollowWizardStepUrlOptions {
+    /** Where the wizard currently is, from `useWizard`. */
+    activeStep: string;
+    /** The flow's first step — where an address carrying no step points. */
+    entryStep: string;
+    /**
+     * `useWizard`'s `goTo`. It ignores a step that is not on the path already
+     * walked, which is what makes browser-Forward safe to hand straight to it.
+     */
+    goTo: (stepId: string) => void;
+}
+/**
+ * Moves the wizard when the address moves, so browser-Back moves a step instead
+ * of leaving the flow.
+ *
+ * **Back works; Forward deliberately does not re-advance.** Going back pops the
+ * history, so the step Forward names is no longer on the path and `goTo` ignores
+ * it — re-entering it would skip the per-step submit that validated everything
+ * in between, which is the only thing gating advancement.
+ *
+ * An address carrying **no** step means the flow's beginning — which is where
+ * browser-Back from the second step lands, since the first step is never pushed.
+ *
+ * ⚠️ **It reacts to the address *changing*, never to what the address says.**
+ * Two faults sit on either side of that, and both were measured:
+ *
+ * - *Rewriting the address to match the wizard* races the advance. The replace
+ *   is scheduled at mount with the entry step captured, the operator advances
+ *   before it lands, and the navigation then puts the older step back — this
+ *   effect reads it and rewinds a step they had already passed. It appeared only
+ *   under load, which is the kind of race that reaches a user and not a test.
+ * - *Acting on the address at mount* breaks resume. A restored wizard takes its
+ *   position from the persisted draft, so it opens on step four with an address
+ *   that says nothing — read as "the beginning", that sends it back to step one
+ *   and the resume is undone.
+ *
+ * So the first address seen is a **baseline**, and only a move away from it is a
+ * navigation. One direction throughout: the writer owns the address, the
+ * follower owns the wizard.
+ */
+export declare function useFollowWizardStepUrl({ activeStep, entryStep, goTo, }: FollowWizardStepUrlOptions): void;
+//# sourceMappingURL=use-wizard-step-param.d.ts.map

package/dist/lib/wizard/use-wizard-step-param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-wizard-step-param.d.ts","sourceRoot":"","sources":["../../../src/lib/wizard/use-wizard-step-param.ts"],"names":[],"mappings":"AAKA,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAuBxC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAY3D;AAED,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,UAAU,EACV,SAAS,EACT,IAAI,GACL,EAAE,0BAA0B,GAAG,IAAI,CAUnC"}