@honua/app-platform 0.0.20-alpha.0

package/scene-workspace/workspace.js

@@ -0,0 +1,391 @@
+import { featureSelectionKey } from "../exploration/index.js";
+export function emptySceneWorkspaceState() {
+    return {
+        layers: {},
+        primitives: {},
+        diagnostics: [],
+        filters: {},
+        detail: {},
+        bookmarks: {},
+        selection: [],
+        timeline: {},
+        evidence: {},
+        realtime: { status: "idle" },
+        history: [],
+    };
+}
+export function createSceneWorkspace(initialState = {}) {
+    let state = mergeState(emptySceneWorkspaceState(), initialState);
+    const listeners = new Map();
+    let disposed = false;
+    function ensureLive() {
+        if (disposed)
+            throw new Error("SceneWorkspace has been disposed.");
+    }
+    function emit(event) {
+        for (const listener of listeners.get("all") ?? [])
+            listener(event);
+        for (const slice of event.changedSlices) {
+            if (slice === "all")
+                continue;
+            for (const listener of listeners.get(slice) ?? [])
+                listener(event);
+        }
+    }
+    return {
+        get state() {
+            return state;
+        },
+        dispatch(intent) {
+            ensureLive();
+            const previous = state;
+            const next = reduceSceneWorkspaceState(state, intent);
+            const changedSlices = changedSceneWorkspaceSlices(previous, next);
+            if (changedSlices.size === 0)
+                return state;
+            state = next;
+            emit({ state, previous, changedSlices, intent });
+            return state;
+        },
+        subscribe(slice, listener) {
+            ensureLive();
+            const sliceListeners = listeners.get(slice) ?? new Set();
+            sliceListeners.add(listener);
+            listeners.set(slice, sliceListeners);
+            return () => {
+                sliceListeners.delete(listener);
+            };
+        },
+        snapshot() {
+            ensureLive();
+            return { version: 1, state: cloneSceneWorkspaceState(state) };
+        },
+        restore(snapshot) {
+            return this.dispatch({ kind: "restore", snapshot, source: "workspace" });
+        },
+        dispose() {
+            disposed = true;
+            listeners.clear();
+        },
+    };
+}
+export function reduceSceneWorkspaceState(state, intent) {
+    const base = applyIntent(state, intent);
+    return appendHistory(base, intent);
+}
+export function sceneWorkspaceIntentFromAdapterEvent(event, source = "scene") {
+    switch (event.type) {
+        case "camera-change":
+            return { kind: "set-camera", camera: event.camera, source, historyLabel: "Scene camera changed" };
+        case "layer-visibility-change":
+            return {
+                kind: "set-layer-visibility",
+                layerId: event.layerId,
+                visible: event.visible,
+                source,
+                historyLabel: "Scene layer visibility changed",
+            };
+        case "primitive-diagnostics":
+            return {
+                kind: "set-diagnostics",
+                diagnostics: event.diagnostics,
+                source,
+                historyLabel: "Scene primitive diagnostics changed",
+            };
+        case "filter-change":
+            return event.clause
+                ? {
+                    kind: "set-filter",
+                    id: event.id,
+                    clause: event.clause,
+                    source,
+                    historyLabel: "Scene filter changed",
+                }
+                : { kind: "clear-filter", id: event.id, source, historyLabel: "Scene filter cleared" };
+        case "selection-change":
+            return { kind: "set-selection", selection: event.selection, source, historyLabel: "Scene selection changed" };
+        case "detail-change":
+            return { kind: "set-detail", detail: event.detail, source, historyLabel: "Scene detail changed" };
+        case "timeline-change":
+            return { kind: "set-timeline", timeline: event.timeline, source, historyLabel: "Scene timeline changed" };
+        case "evidence-add":
+            if (!event.evidence)
+                throw new Error("evidence-add adapter event requires evidence.");
+            return { kind: "add-evidence", evidence: event.evidence, source, historyLabel: "Scene evidence added" };
+        case "evidence-remove":
+            if (!event.id)
+                throw new Error("evidence-remove adapter event requires id.");
+            return { kind: "remove-evidence", id: event.id, source, historyLabel: "Scene evidence removed" };
+        case "realtime-status":
+            return { kind: "set-realtime", realtime: event.realtime, source, historyLabel: "Scene realtime status changed" };
+    }
+}
+export function selectSceneVisibleLayers(state) {
+    return Object.values(state.layers).filter((layer) => layer.visible);
+}
+export function selectScenePrimitivesByKind(state, kind) {
+    return Object.values(state.primitives).filter((primitive) => primitive.kind === kind);
+}
+export function selectSceneDiagnosticsByStatus(state, status) {
+    return state.diagnostics.filter((diagnostic) => diagnostic.status === status);
+}
+export function selectSceneEvidenceForFeature(state, featureId) {
+    if (featureId === undefined)
+        return [];
+    return Object.values(state.evidence).filter((evidence) => evidence.featureId === featureId);
+}
+function applyIntent(state, intent) {
+    switch (intent.kind) {
+        case "set-scene":
+            return {
+                ...state,
+                sceneId: intent.sceneId,
+                title: intent.title,
+            };
+        case "set-layers":
+            return {
+                ...state,
+                layers: Object.fromEntries(intent.layers.map((layer) => [layer.id, { ...layer }])),
+            };
+        case "set-primitives":
+            return {
+                ...state,
+                primitives: Object.fromEntries(intent.primitives.map((primitive) => [primitive.id, clonePrimitive(primitive)])),
+            };
+        case "set-diagnostics":
+            return {
+                ...state,
+                diagnostics: intent.diagnostics.map(cloneDiagnostic),
+            };
+        case "set-layer-visibility": {
+            const existing = state.layers[intent.layerId];
+            return {
+                ...state,
+                layers: {
+                    ...state.layers,
+                    [intent.layerId]: {
+                        ...existing,
+                        id: intent.layerId,
+                        visible: intent.visible,
+                    },
+                },
+            };
+        }
+        case "set-camera":
+            return {
+                ...state,
+                camera: intent.camera ? { ...intent.camera } : undefined,
+            };
+        case "apply-bookmark":
+            return {
+                ...state,
+                camera: { ...intent.bookmark.camera },
+                bookmarks: {
+                    ...state.bookmarks,
+                    [intent.bookmark.id]: { ...intent.bookmark, camera: { ...intent.bookmark.camera } },
+                },
+            };
+        case "set-filter":
+            return {
+                ...state,
+                filters: {
+                    ...state.filters,
+                    [intent.id]: cloneValue(intent.clause),
+                },
+            };
+        case "clear-filter": {
+            const filters = { ...state.filters };
+            delete filters[intent.id];
+            return { ...state, filters };
+        }
+        case "set-selection":
+            return {
+                ...state,
+                selection: dedupeSelection(intent.selection),
+            };
+        case "clear-selection":
+            return {
+                ...state,
+                selection: [],
+            };
+        case "set-detail":
+            return {
+                ...state,
+                detail: cloneDetail(intent.detail),
+            };
+        case "set-active-asset":
+            return {
+                ...state,
+                activeAssetId: intent.id,
+            };
+        case "set-timeline":
+            return {
+                ...state,
+                timeline: { ...intent.timeline },
+            };
+        case "add-evidence":
+            return {
+                ...state,
+                evidence: {
+                    ...state.evidence,
+                    [intent.evidence.id]: cloneEvidence(intent.evidence),
+                },
+            };
+        case "remove-evidence": {
+            const evidence = { ...state.evidence };
+            delete evidence[intent.id];
+            return { ...state, evidence };
+        }
+        case "set-realtime":
+            return {
+                ...state,
+                realtime: { ...intent.realtime },
+            };
+        case "restore":
+            return cloneSceneWorkspaceState(intent.snapshot.state);
+    }
+}
+function appendHistory(state, intent) {
+    if (intent.kind === "restore")
+        return state;
+    const label = intent.historyLabel ?? intent.kind;
+    const at = intent.at ?? new Date().toISOString();
+    const entry = {
+        id: `${state.history.length + 1}:${intent.kind}`,
+        label,
+        at,
+        intentKind: intent.kind,
+    };
+    return {
+        ...state,
+        history: [...state.history, entry].slice(-50),
+    };
+}
+function changedSceneWorkspaceSlices(previous, next) {
+    const changed = new Set();
+    if (previous.sceneId !== next.sceneId || previous.title !== next.title)
+        changed.add("scene");
+    if (previous.camera !== next.camera)
+        changed.add("camera");
+    if (previous.layers !== next.layers)
+        changed.add("layers");
+    if (previous.primitives !== next.primitives)
+        changed.add("primitives");
+    if (previous.diagnostics !== next.diagnostics)
+        changed.add("diagnostics");
+    if (previous.filters !== next.filters)
+        changed.add("filters");
+    if (previous.detail !== next.detail)
+        changed.add("detail");
+    if (previous.selection !== next.selection)
+        changed.add("selection");
+    if (previous.timeline !== next.timeline)
+        changed.add("timeline");
+    if (previous.evidence !== next.evidence)
+        changed.add("evidence");
+    if (previous.realtime !== next.realtime)
+        changed.add("realtime");
+    if (previous.history !== next.history)
+        changed.add("history");
+    return changed;
+}
+function mergeState(base, initial) {
+    return cloneSceneWorkspaceState({
+        ...base,
+        ...initial,
+        layers: {
+            ...base.layers,
+            ...Object.fromEntries(Object.entries(initial.layers ?? {}).map(([id, layer]) => [id, cloneLayer(layer)])),
+        },
+        primitives: {
+            ...base.primitives,
+            ...Object.fromEntries(Object.entries(initial.primitives ?? {}).map(([id, primitive]) => [id, clonePrimitive(primitive)])),
+        },
+        diagnostics: initial.diagnostics ? initial.diagnostics.map(cloneDiagnostic) : base.diagnostics,
+        filters: {
+            ...base.filters,
+            ...cloneValue(initial.filters ?? {}),
+        },
+        detail: cloneDetail({ ...base.detail, ...initial.detail }),
+        bookmarks: {
+            ...base.bookmarks,
+            ...Object.fromEntries(Object.entries(initial.bookmarks ?? {}).map(([id, bookmark]) => [id, cloneBookmark(bookmark)])),
+        },
+        selection: initial.selection ? dedupeSelection(initial.selection) : base.selection,
+        timeline: { ...base.timeline, ...initial.timeline },
+        evidence: {
+            ...base.evidence,
+            ...Object.fromEntries(Object.entries(initial.evidence ?? {}).map(([id, evidence]) => [id, cloneEvidence(evidence)])),
+        },
+        realtime: { ...base.realtime, ...initial.realtime },
+        history: [...(initial.history ?? base.history)],
+    });
+}
+function cloneSceneWorkspaceState(state) {
+    return {
+        ...state,
+        layers: Object.fromEntries(Object.entries(state.layers).map(([id, layer]) => [id, cloneLayer(layer)])),
+        primitives: Object.fromEntries(Object.entries(state.primitives).map(([id, primitive]) => [id, clonePrimitive(primitive)])),
+        diagnostics: state.diagnostics.map(cloneDiagnostic),
+        filters: cloneValue(state.filters),
+        detail: cloneDetail(state.detail),
+        bookmarks: Object.fromEntries(Object.entries(state.bookmarks).map(([id, bookmark]) => [id, cloneBookmark(bookmark)])),
+        camera: state.camera ? cloneCamera(state.camera) : undefined,
+        selection: dedupeSelection(state.selection),
+        timeline: { ...state.timeline },
+        evidence: Object.fromEntries(Object.entries(state.evidence).map(([id, evidence]) => [id, cloneEvidence(evidence)])),
+        realtime: { ...state.realtime },
+        history: state.history.map((entry) => ({ ...entry })),
+    };
+}
+function cloneLayer(layer) {
+    return { ...layer };
+}
+function clonePrimitive(primitive) {
+    return cloneValue(primitive);
+}
+function cloneDiagnostic(diagnostic) {
+    return cloneValue(diagnostic);
+}
+function cloneDetail(detail) {
+    return {
+        ...detail,
+        target: detail.target ? cloneSelectionTarget(detail.target) : undefined,
+        attributes: detail.attributes ? cloneValue(detail.attributes) : undefined,
+    };
+}
+function cloneCamera(camera) {
+    return { ...camera };
+}
+function cloneBookmark(bookmark) {
+    return {
+        ...bookmark,
+        camera: cloneCamera(bookmark.camera),
+    };
+}
+function cloneEvidence(evidence) {
+    return {
+        ...evidence,
+        metadata: evidence.metadata ? cloneValue(evidence.metadata) : undefined,
+    };
+}
+function dedupeSelection(selection) {
+    const seen = new Set();
+    const out = [];
+    for (const target of selection) {
+        const key = featureSelectionKey(target);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(cloneSelectionTarget(target));
+    }
+    return out;
+}
+function cloneSelectionTarget(target) {
+    return typeof target === "object" && target !== null ? { ...target } : target;
+}
+function cloneValue(value) {
+    if (typeof structuredClone === "function")
+        return structuredClone(value);
+    return JSON.parse(JSON.stringify(value));
+}

package/share/denial.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Anonymous-safe Share access states and denial helpers.
+ *
+ * Mirrors the server's anonymous Share endpoints: unknown, expired, revoked,
+ * forbidden, or no-longer-covered tokens all collapse to a single, identical
+ * denial that never discloses item identity, title, or existence. Browser code
+ * consumes one explicit state model rather than inferring access from HTTP
+ * status codes or—worse—leaking a private title into a "not allowed" message.
+ *
+ * @module
+ */
+import type { HonuaEmbedRedemption, HonuaPublicLinkResolution } from "./types.js";
+/**
+ * Why an anonymous Share read was denied. These are intentionally coarse so the
+ * reason never acts as an existence/identity oracle: `not-found` covers unknown
+ * items, revoked/unknown tokens, and items whose tier no longer covers the
+ * access path; `expired` covers tokens past their TTL; `forbidden` covers a
+ * surface that exists but is not anonymously readable through the attempted
+ * mechanism.
+ */
+export type HonuaShareDenialReason = "not-found" | "expired" | "forbidden";
+/** The mechanism an anonymous read was attempted through. */
+export type HonuaShareAccessKind = "public-link" | "public-content" | "embed";
+/**
+ * Granted anonymous Share state — the resolved presentation projection plus the
+ * access kind it was reached through.
+ */
+export interface HonuaShareAccessGranted<TResolution> {
+    readonly status: "granted";
+    readonly kind: HonuaShareAccessKind;
+    readonly resolution: TResolution;
+}
+/**
+ * Denied anonymous Share state. Carries only a coarse {@link reason} and an
+ * opaque, identity-free {@link message}. It deliberately exposes no item id,
+ * title, or any field that could confirm a private item exists.
+ */
+export interface HonuaShareAccessDenied {
+    readonly status: "denied";
+    readonly kind: HonuaShareAccessKind;
+    readonly reason: HonuaShareDenialReason;
+    /** Opaque, anonymous-safe denial message. Never includes item identity. */
+    readonly message: string;
+}
+/** Discriminated anonymous Share access state. */
+export type HonuaShareAccessState<TResolution> = HonuaShareAccessGranted<TResolution> | HonuaShareAccessDenied;
+/** Anonymous Share access state for a public-link / public-content read. */
+export type HonuaPublicLinkAccessState = HonuaShareAccessState<HonuaPublicLinkResolution>;
+/** Anonymous Share access state for an embed redemption. */
+export type HonuaEmbedAccessState = HonuaShareAccessState<HonuaEmbedRedemption>;
+/**
+ * Constant, identity-free denial messages keyed by access kind. These mirror
+ * the server's fixed denial bodies so the browser never has to synthesize a
+ * message from item data. They are byte-stable per kind so a denial response
+ * cannot be distinguished by message content.
+ */
+export declare const HONUA_SHARE_DENIAL_MESSAGES: Readonly<Record<HonuaShareAccessKind, string>>;
+/**
+ * Builds an anonymous-safe denial state. The message is always sourced from
+ * {@link HONUA_SHARE_DENIAL_MESSAGES} and never from caller-supplied item data,
+ * so private titles cannot leak through this path.
+ */
+export declare function denyShareAccess(kind: HonuaShareAccessKind, reason: HonuaShareDenialReason): HonuaShareAccessDenied;
+/** Builds a granted Share access state from a resolved presentation projection. */
+export declare function grantShareAccess<TResolution>(kind: HonuaShareAccessKind, resolution: TResolution): HonuaShareAccessGranted<TResolution>;
+/** Narrowing guard for the denied state. */
+export declare function isShareAccessDenied<TResolution>(state: HonuaShareAccessState<TResolution>): state is HonuaShareAccessDenied;
+/** Narrowing guard for the granted state. */
+export declare function isShareAccessGranted<TResolution>(state: HonuaShareAccessState<TResolution>): state is HonuaShareAccessGranted<TResolution>;
+/**
+ * Maps an anonymous Share endpoint HTTP status to a denial state. The server
+ * collapses unknown/expired/revoked/forbidden into a uniform `404`, so any
+ * non-2xx status becomes a `not-found` denial unless it is a `403`
+ * (`forbidden`) or `410` (`expired`). This keeps browser callers from leaking
+ * an existence oracle by branching on richer statuses.
+ */
+export declare function denialFromHttpStatus(kind: HonuaShareAccessKind, status: number): HonuaShareAccessDenied;
+//# sourceMappingURL=denial.d.ts.map

package/share/denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denial.d.ts","sourceRoot":"","sources":["../../../src/share/denial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;AAE3E,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CAAC,WAAW;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,MAAM,qBAAqB,CAAC,WAAW,IAAI,uBAAuB,CAAC,WAAW,CAAC,GAAG,sBAAsB,CAAC;AAE/G,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAAG,qBAAqB,CAAC,yBAAyB,CAAC,CAAC;AAE1F,4DAA4D;AAC5D,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAI7E,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAOlH;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,WAAW,EAC1C,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,WAAW,GACtB,uBAAuB,CAAC,WAAW,CAAC,CAEtC;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,WAAW,EAC7C,KAAK,EAAE,qBAAqB,CAAC,WAAW,CAAC,GACxC,KAAK,IAAI,sBAAsB,CAEjC;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,WAAW,EAC9C,KAAK,EAAE,qBAAqB,CAAC,WAAW,CAAC,GACxC,KAAK,IAAI,uBAAuB,CAAC,WAAW,CAAC,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,sBAAsB,CAIvG"}

package/share/denial.js

@@ -0,0 +1,61 @@
+/**
+ * Anonymous-safe Share access states and denial helpers.
+ *
+ * Mirrors the server's anonymous Share endpoints: unknown, expired, revoked,
+ * forbidden, or no-longer-covered tokens all collapse to a single, identical
+ * denial that never discloses item identity, title, or existence. Browser code
+ * consumes one explicit state model rather than inferring access from HTTP
+ * status codes or—worse—leaking a private title into a "not allowed" message.
+ *
+ * @module
+ */
+/**
+ * Constant, identity-free denial messages keyed by access kind. These mirror
+ * the server's fixed denial bodies so the browser never has to synthesize a
+ * message from item data. They are byte-stable per kind so a denial response
+ * cannot be distinguished by message content.
+ */
+export const HONUA_SHARE_DENIAL_MESSAGES = {
+    "public-link": "Link not found or expired.",
+    "public-content": "Shared item not found.",
+    embed: "Embed token not found or expired.",
+};
+/**
+ * Builds an anonymous-safe denial state. The message is always sourced from
+ * {@link HONUA_SHARE_DENIAL_MESSAGES} and never from caller-supplied item data,
+ * so private titles cannot leak through this path.
+ */
+export function denyShareAccess(kind, reason) {
+    return {
+        status: "denied",
+        kind,
+        reason,
+        message: HONUA_SHARE_DENIAL_MESSAGES[kind] ?? HONUA_SHARE_DENIAL_MESSAGES["public-content"],
+    };
+}
+/** Builds a granted Share access state from a resolved presentation projection. */
+export function grantShareAccess(kind, resolution) {
+    return { status: "granted", kind, resolution };
+}
+/** Narrowing guard for the denied state. */
+export function isShareAccessDenied(state) {
+    return state.status === "denied";
+}
+/** Narrowing guard for the granted state. */
+export function isShareAccessGranted(state) {
+    return state.status === "granted";
+}
+/**
+ * Maps an anonymous Share endpoint HTTP status to a denial state. The server
+ * collapses unknown/expired/revoked/forbidden into a uniform `404`, so any
+ * non-2xx status becomes a `not-found` denial unless it is a `403`
+ * (`forbidden`) or `410` (`expired`). This keeps browser callers from leaking
+ * an existence oracle by branching on richer statuses.
+ */
+export function denialFromHttpStatus(kind, status) {
+    if (status === 403)
+        return denyShareAccess(kind, "forbidden");
+    if (status === 410)
+        return denyShareAccess(kind, "expired");
+    return denyShareAccess(kind, "not-found");
+}

package/share/embed-token.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fragment-only embed-token parsing.
+ *
+ * Embed bearer tokens MUST travel in the URL fragment (`#...`), never the query
+ * string. The fragment is not sent to the origin server, is not written to
+ * server access logs or the `Referer` header, and is not captured by most
+ * proxy/CDN request logging — so a fragment-borne bearer token has a much
+ * smaller disclosure surface than a query-string one. This helper extracts a
+ * token from the fragment and *rejects* query-string bearer patterns outright
+ * so a generated app or embed never silently accepts a leak-prone placement.
+ *
+ * @module
+ */
+/** Default fragment parameter name an embed token is read from. */
+export declare const HONUA_EMBED_TOKEN_FRAGMENT_PARAM: "embed_token";
+/** Why an embed-token parse rejected an input. */
+export type HonuaEmbedTokenRejectionReason = 
+/** No token was present in the fragment. */
+"missing"
+/** The token appeared in the query string — a forbidden, leak-prone placement. */
+ | "query-string-token"
+/** The fragment held a token-shaped value but it was empty/blank. */
+ | "empty"
+/** The input was not a parseable URL or fragment. */
+ | "malformed";
+/** Successful fragment-only token parse. */
+export interface HonuaEmbedTokenParseOk {
+    readonly ok: true;
+    /** The extracted opaque token value (trimmed, never empty). */
+    readonly token: string;
+    /** The fragment parameter the token was read from. */
+    readonly param: string;
+}
+/** Rejected token parse — carries a reason but never the offending value. */
+export interface HonuaEmbedTokenParseRejected {
+    readonly ok: false;
+    readonly reason: HonuaEmbedTokenRejectionReason;
+}
+/** Result of {@link parseEmbedTokenFromFragment}. */
+export type HonuaEmbedTokenParseResult = HonuaEmbedTokenParseOk | HonuaEmbedTokenParseRejected;
+/** Options for {@link parseEmbedTokenFromFragment}. */
+export interface ParseEmbedTokenOptions {
+    /**
+     * Fragment parameter name(s) to read the token from. Defaults to
+     * {@link HONUA_EMBED_TOKEN_FRAGMENT_PARAM}. The same name(s) are also the
+     * query-string keys that are rejected if a token is found there.
+     */
+    readonly param?: string | readonly string[];
+}
+/**
+ * Extracts an embed bearer token from a URL/location fragment, rejecting any
+ * token placed in the query string.
+ *
+ * Resolution order:
+ * 1. If a token parameter is present in the **query string**, reject with
+ *    `query-string-token` — even if a fragment token also exists — so a
+ *    leak-prone placement is never silently tolerated.
+ * 2. Otherwise read the token from the **fragment**. A blank fragment token
+ *    rejects with `empty`; a missing one rejects with `missing`.
+ *
+ * @param input A full or relative URL, a bare query, or a bare fragment. In a
+ *   browser, pass `window.location.href` (or `location.search + location.hash`).
+ */
+export declare function parseEmbedTokenFromFragment(input: string, options?: ParseEmbedTokenOptions): HonuaEmbedTokenParseResult;
+/**
+ * Convenience guard: `true` when `input` carries an embed-token parameter in the
+ * query string (any leak-prone placement). Useful for asserting a redirect
+ * stripped the token before it reached a logged surface.
+ */
+export declare function hasQueryStringEmbedToken(input: string, options?: ParseEmbedTokenOptions): boolean;
+//# sourceMappingURL=embed-token.d.ts.map

package/share/embed-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-token.d.ts","sourceRoot":"","sources":["../../../src/share/embed-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,EAAG,aAAsB,CAAC;AAEvE,kDAAkD;AAClD,MAAM,MAAM,8BAA8B;AACxC,4CAA4C;AAC1C,SAAS;AACX,kFAAkF;GAChF,oBAAoB;AACtB,qEAAqE;GACnE,OAAO;AACT,qDAAqD;GACnD,WAAW,CAAC;AAEhB,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;CACjD;AAED,qDAAqD;AACrD,MAAM,MAAM,0BAA0B,GAAG,sBAAsB,GAAG,4BAA4B,CAAC;AAE/F,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CAC7C;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAA2B,GACnC,0BAA0B,CAmB5B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAKrG"}