@north-light/crouter 0.3.197 → 0.3.199

package/dist/pages/entry.d.ts

@@ -1,8 +0,0 @@
-import './bundle.css';
-import './elements/options.js';
-import './elements/text.js';
-import './elements/table.js';
-import './elements/cards.js';
-import './elements/chart.js';
-import './elements/pages.js';
-import './elements/slot.js';

package/dist/pages/entry.js

@@ -1,8 +0,0 @@
-import './bundle.css';
-import './elements/options.js';
-import './elements/text.js';
-import './elements/table.js';
-import './elements/cards.js';
-import './elements/chart.js';
-import './elements/pages.js';
-import './elements/slot.js';

package/dist/pages/host.d.ts

@@ -1,158 +0,0 @@
-/**
- * `window.crtr` — the one door out of a page.
- *
- * An element renders inside a host (Northlight's srcdoc host today, a crtrd-served
- * page later) that installs this bridge before the bundle loads. Everything an element
- * needs from the outside world arrives through it: there is no `fetch`, no `XMLHttpRequest`,
- * no direct network access anywhere under `src/pages/`. An element that cannot get what it
- * needs renders a named unavailable state; it never falls back to reaching out itself.
- *
- * Two things the bridge deliberately does NOT have:
- *
- *  - **No `save` and no `dismiss`.** Both are host chrome — a frame around the page, not
- *    markup inside it — so they are the host's own UI actions and are never advertised to
- *    page code.
- *  - **No per-element resolution.** `respond()` is a local-state write plus a request that
- *    the host autosave the partial map; it does not resolve the ticket. Only the pager's
- *    submit affordance calls `submit()`, which posts the complete map once.
- *
- * `respond()` has one counterpart, `savedResponse()`: the host hands back the response it is
- * currently holding for a slot, so a page reopened after a partial answer re-mounts SHOWING
- * that answer instead of blank. Every response-bearing element reads it at mount and seeds
- * its visible state from it — that is what keeps "what submit sends" and "what the screen
- * shows" the same thing.
- *
- * The host is optional at the type level (`window.crtr?`) because a page can be opened
- * bare — dropped in a browser, or rendered by a host that installs nothing. Elements read
- * the bridge through the accessors below rather than touching `window.crtr` directly, so
- * that absence is typed and total instead of an `as any` at each call site.
- */
-import type { SlotResponse } from './types.js';
-/** Live host theme tokens, as `--crtr-*` custom-property names mapped to values. */
-export interface CrtrThemeBridge {
-    current(): Record<string, string>;
-    /** Registers `listener` for later theme changes; returns its unsubscribe. */
-    subscribe(listener: (tokens: Record<string, string>) => void): () => void;
-}
-/** Data behind a `source`-bearing config (table, cards, chart). */
-export interface CrtrArtifactBridge {
-    /** Resolves the already-parsed data for `source`, or rejects when it is unreachable. */
-    data(source: string): Promise<unknown>;
-}
-/** What `mountWorkspaceComponent` can answer: the host rendered it, or it has no renderer. */
-export type WorkspaceMountOutcome = 'mounted' | 'unavailable';
-/** The bridge a host installs at `window.crtr`. */
-export interface CrtrHost {
-    /**
-     * Records this slot's complete current response and asks the host to autosave the
-     * partial map. Called on every user change. NOT ticket resolution.
-     */
-    respond(slotId: string, response: SlotResponse): void;
-    /**
-     * The response the host currently holds for this slot — an autosaved partial answer on a
-     * reopened page, or the published answer on a resolved one. `undefined` when the host has
-     * nothing for the slot. Elements read it at mount; it is the inbound half of `respond`.
-     */
-    savedResponse(slotId: string): SlotResponse | undefined;
-    /** Posts the complete response map once. Only the pager's submit affordance calls it. */
-    submit(): Promise<void>;
-    /** Flushes the pending autosave of the partial map. */
-    progress(): Promise<void>;
-    readonly theme: CrtrThemeBridge;
-    readonly artifact: CrtrArtifactBridge;
-    /**
-     * Asks the host to render a product-registered (`unvalidated`) slot into `element`.
-     * A host with no renderer for `kind` answers `'unavailable'`.
-     */
-    mountWorkspaceComponent(element: HTMLElement, kind: string, config: Record<string, unknown>): Promise<WorkspaceMountOutcome>;
-}
-declare global {
-    interface Window {
-        /**
-         * Installed by the host before the bundle loads. Optional: a page opened bare has
-         * no bridge, and every element must still render.
-         */
-        crtr?: CrtrHost;
-    }
-}
-/**
- * The outcome of a bridge call. `unavailable` means the door is not there — no host, or a
- * host that does not implement this method. `failed` means the host was asked and said no,
- * and `reason` is what it said. Elements distinguish them because "this page is not hosted"
- * and "the server rejected your answer" are different things to show a person.
- */
-export type HostCall = {
-    status: 'ok';
-} | {
-    status: 'unavailable';
-    reason: string;
-} | {
-    status: 'failed';
-    reason: string;
-};
-/** The outcome of an artifact read, with the same three-way split as `HostCall`. */
-export type ArtifactData = {
-    status: 'ok';
-    data: unknown;
-} | {
-    status: 'unavailable';
-    reason: string;
-} | {
-    status: 'failed';
-    reason: string;
-};
-/** The installed bridge, or `undefined` on a bare page. */
-export declare function host(): CrtrHost | undefined;
-/**
- * Writes this slot's complete current response to the host's in-frame map and requests an
- * autosave. Elements call this on every user change with the whole response object, never a
- * delta. Safe on a bare page: the element's own local state is authoritative for rendering,
- * so an unavailable host only means the answer is not being persisted.
- */
-export declare function respond(slotId: string, response: SlotResponse): HostCall;
-/**
- * The response the host already holds for this slot, or `undefined` when it holds none — a
- * bare page, a first open, or a host without the channel. Elements call this once at mount
- * and seed their visible state from it, so a reopened page shows the answers the host would
- * submit rather than an empty form beside a full response map.
- *
- * `T` is asserted, not verified, exactly like `readSlotConfig`'s config: the host's saved map
- * was validated against this slot's kind before it was stored. What is not guaranteed is that
- * a host implements the channel at all, which is what the `undefined` covers — so seed with
- * the same defensiveness you would give any outside value (`savedIds`, `adoptComments`).
- */
-export declare function savedResponse<T extends SlotResponse = SlotResponse>(slotId: string): T | undefined;
-/** The string ids of a saved selection field, with anything else in it dropped. */
-export declare function savedIds(value: unknown): string[];
-/**
- * Posts the complete response map once, resolving the ticket. Only the pager's submit
- * affordance calls this.
- */
-export declare function submit(): Promise<HostCall>;
-/** Flushes the host's pending autosave of the partial map. Never resolves the ticket. */
-export declare function progress(): Promise<HostCall>;
-/**
- * The host's current theme token values. Empty on a bare page — which is correct and needs
- * no handling, because `bundle.css` declares every `--crtr-*` token at zero specificity and
- * elements style through those custom properties rather than through this map. Read it only
- * when a value must reach somewhere CSS cannot, such as an SVG attribute.
- */
-export declare function themeTokens(): Record<string, string>;
-/**
- * Subscribes to later theme changes. Always returns an unsubscribe, so a caller can wire it
- * to `disconnectedCallback` without checking whether a host was there.
- */
-export declare function subscribeTheme(listener: (tokens: Record<string, string>) => void): () => void;
-/**
- * Reads the data behind a `source`-bearing config. The host resolves the reference and hands
- * back parsed data; an element never resolves a reference itself and never fetches a URL.
- * Anything other than `'ok'` is a named unavailable state to render, not a reason to retry
- * some other way.
- */
-export declare function artifactData(source: string): Promise<ArtifactData>;
-/**
- * Asks the host to render a product-registered slot into `element`. A bare page, a host with
- * no registry, and a host whose mount threw all answer `'unavailable'` — the escape element's
- * named unavailable state is the only other outcome.
- */
-export declare function mountWorkspaceComponent(element: HTMLElement, kind: string, config: Record<string, unknown>): Promise<WorkspaceMountOutcome>;

package/dist/pages/host.js

@@ -1,182 +0,0 @@
-/**
- * `window.crtr` — the one door out of a page.
- *
- * An element renders inside a host (Northlight's srcdoc host today, a crtrd-served
- * page later) that installs this bridge before the bundle loads. Everything an element
- * needs from the outside world arrives through it: there is no `fetch`, no `XMLHttpRequest`,
- * no direct network access anywhere under `src/pages/`. An element that cannot get what it
- * needs renders a named unavailable state; it never falls back to reaching out itself.
- *
- * Two things the bridge deliberately does NOT have:
- *
- *  - **No `save` and no `dismiss`.** Both are host chrome — a frame around the page, not
- *    markup inside it — so they are the host's own UI actions and are never advertised to
- *    page code.
- *  - **No per-element resolution.** `respond()` is a local-state write plus a request that
- *    the host autosave the partial map; it does not resolve the ticket. Only the pager's
- *    submit affordance calls `submit()`, which posts the complete map once.
- *
- * `respond()` has one counterpart, `savedResponse()`: the host hands back the response it is
- * currently holding for a slot, so a page reopened after a partial answer re-mounts SHOWING
- * that answer instead of blank. Every response-bearing element reads it at mount and seeds
- * its visible state from it — that is what keeps "what submit sends" and "what the screen
- * shows" the same thing.
- *
- * The host is optional at the type level (`window.crtr?`) because a page can be opened
- * bare — dropped in a browser, or rendered by a host that installs nothing. Elements read
- * the bridge through the accessors below rather than touching `window.crtr` directly, so
- * that absence is typed and total instead of an `as any` at each call site.
- */
-/** The installed bridge, or `undefined` on a bare page. */
-export function host() {
-    return typeof window === 'undefined' ? undefined : window.crtr;
-}
-function reasonOf(error) {
-    if (error instanceof Error && error.message !== '')
-        return error.message;
-    const text = String(error);
-    return text === '' ? 'unknown error' : text;
-}
-function missing(method) {
-    return { status: 'unavailable', reason: `host bridge does not provide ${method}()` };
-}
-/**
- * Writes this slot's complete current response to the host's in-frame map and requests an
- * autosave. Elements call this on every user change with the whole response object, never a
- * delta. Safe on a bare page: the element's own local state is authoritative for rendering,
- * so an unavailable host only means the answer is not being persisted.
- */
-export function respond(slotId, response) {
-    const bridge = host();
-    if (typeof bridge?.respond !== 'function')
-        return missing('respond');
-    try {
-        bridge.respond(slotId, response);
-        return { status: 'ok' };
-    }
-    catch (error) {
-        return { status: 'failed', reason: reasonOf(error) };
-    }
-}
-/**
- * The response the host already holds for this slot, or `undefined` when it holds none — a
- * bare page, a first open, or a host without the channel. Elements call this once at mount
- * and seed their visible state from it, so a reopened page shows the answers the host would
- * submit rather than an empty form beside a full response map.
- *
- * `T` is asserted, not verified, exactly like `readSlotConfig`'s config: the host's saved map
- * was validated against this slot's kind before it was stored. What is not guaranteed is that
- * a host implements the channel at all, which is what the `undefined` covers — so seed with
- * the same defensiveness you would give any outside value (`savedIds`, `adoptComments`).
- */
-export function savedResponse(slotId) {
-    const bridge = host();
-    if (typeof bridge?.savedResponse !== 'function')
-        return undefined;
-    try {
-        const saved = bridge.savedResponse(slotId);
-        return typeof saved === 'object' && saved !== null && !Array.isArray(saved) ? saved : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** The string ids of a saved selection field, with anything else in it dropped. */
-export function savedIds(value) {
-    return Array.isArray(value) ? value.filter((id) => typeof id === 'string') : [];
-}
-/**
- * Posts the complete response map once, resolving the ticket. Only the pager's submit
- * affordance calls this.
- */
-export async function submit() {
-    const bridge = host();
-    if (typeof bridge?.submit !== 'function')
-        return missing('submit');
-    try {
-        await bridge.submit();
-        return { status: 'ok' };
-    }
-    catch (error) {
-        return { status: 'failed', reason: reasonOf(error) };
-    }
-}
-/** Flushes the host's pending autosave of the partial map. Never resolves the ticket. */
-export async function progress() {
-    const bridge = host();
-    if (typeof bridge?.progress !== 'function')
-        return missing('progress');
-    try {
-        await bridge.progress();
-        return { status: 'ok' };
-    }
-    catch (error) {
-        return { status: 'failed', reason: reasonOf(error) };
-    }
-}
-/**
- * The host's current theme token values. Empty on a bare page — which is correct and needs
- * no handling, because `bundle.css` declares every `--crtr-*` token at zero specificity and
- * elements style through those custom properties rather than through this map. Read it only
- * when a value must reach somewhere CSS cannot, such as an SVG attribute.
- */
-export function themeTokens() {
-    const bridge = host();
-    if (typeof bridge?.theme?.current !== 'function')
-        return {};
-    try {
-        return bridge.theme.current();
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Subscribes to later theme changes. Always returns an unsubscribe, so a caller can wire it
- * to `disconnectedCallback` without checking whether a host was there.
- */
-export function subscribeTheme(listener) {
-    const bridge = host();
-    if (typeof bridge?.theme?.subscribe !== 'function')
-        return () => { };
-    try {
-        const unsubscribe = bridge.theme.subscribe(listener);
-        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
-    }
-    catch {
-        return () => { };
-    }
-}
-/**
- * Reads the data behind a `source`-bearing config. The host resolves the reference and hands
- * back parsed data; an element never resolves a reference itself and never fetches a URL.
- * Anything other than `'ok'` is a named unavailable state to render, not a reason to retry
- * some other way.
- */
-export async function artifactData(source) {
-    const bridge = host();
-    if (typeof bridge?.artifact?.data !== 'function')
-        return missing('artifact.data');
-    try {
-        return { status: 'ok', data: await bridge.artifact.data(source) };
-    }
-    catch (error) {
-        return { status: 'failed', reason: reasonOf(error) };
-    }
-}
-/**
- * Asks the host to render a product-registered slot into `element`. A bare page, a host with
- * no registry, and a host whose mount threw all answer `'unavailable'` — the escape element's
- * named unavailable state is the only other outcome.
- */
-export async function mountWorkspaceComponent(element, kind, config) {
-    const bridge = host();
-    if (typeof bridge?.mountWorkspaceComponent !== 'function')
-        return 'unavailable';
-    try {
-        return await bridge.mountWorkspaceComponent(element, kind, config);
-    }
-    catch {
-        return 'unavailable';
-    }
-}

package/dist/pages/register.d.ts

@@ -1,2 +0,0 @@
-export type CrtrElementName = `crtr-${string}`;
-export declare function registerElement(name: CrtrElementName, element: CustomElementConstructor): void;

package/dist/pages/register.js

@@ -1,3 +0,0 @@
-export function registerElement(name, element) {
-    customElements.define(name, element);
-}

package/dist/pages/slot-config.d.ts

@@ -1,36 +0,0 @@
-/**
- * Reading a slot's config out of the DOM.
- *
- * The host renders each slot as
- * `<crtr-KIND slot-id="ID"><script type="application/json">CONFIG_JSON</script></crtr-KIND>`,
- * and every element does the same three things in `connectedCallback`: find that script child,
- * parse it, and render a named error state instead of throwing when it is missing or malformed.
- * That is one behaviour, so it lives here once.
- *
- * **What is and is not checked.** The JSON's *shape* was already validated by
- * `validatePageManifest` before the manifest was stored, and the renderer emits from that
- * validated manifest — so an element may trust the parsed object against its own config type.
- * What is not guaranteed is that the script child is there at all and that its text parses: a
- * page can be hand-written, truncated, or rendered by something else. Those two failures are
- * what this module reports.
- */
-/** A parsed config, or the reason the element should render an error state instead. */
-export type SlotConfigResult<T> = {
-    status: 'ok';
-    config: T;
-} | {
-    status: 'invalid';
-    reason: string;
-};
-/**
- * Reads and parses the JSON script child of `element`.
- *
- * `T` is the element's own mirrored config type and is asserted, not verified — see the note
- * above on why that is sound. Never throws.
- */
-export declare function readSlotConfig<T = Record<string, unknown>>(element: HTMLElement): SlotConfigResult<T>;
-/**
- * The slot id the host addressed this element by — the key `respond()` takes. Absent on a
- * display-only slot, which has no id and produces no response.
- */
-export declare function readSlotId(element: HTMLElement): string | undefined;

package/dist/pages/slot-config.js

@@ -1,50 +0,0 @@
-/**
- * Reading a slot's config out of the DOM.
- *
- * The host renders each slot as
- * `<crtr-KIND slot-id="ID"><script type="application/json">CONFIG_JSON</script></crtr-KIND>`,
- * and every element does the same three things in `connectedCallback`: find that script child,
- * parse it, and render a named error state instead of throwing when it is missing or malformed.
- * That is one behaviour, so it lives here once.
- *
- * **What is and is not checked.** The JSON's *shape* was already validated by
- * `validatePageManifest` before the manifest was stored, and the renderer emits from that
- * validated manifest — so an element may trust the parsed object against its own config type.
- * What is not guaranteed is that the script child is there at all and that its text parses: a
- * page can be hand-written, truncated, or rendered by something else. Those two failures are
- * what this module reports.
- */
-/**
- * Reads and parses the JSON script child of `element`.
- *
- * `T` is the element's own mirrored config type and is asserted, not verified — see the note
- * above on why that is sound. Never throws.
- */
-export function readSlotConfig(element) {
-    const script = element.querySelector('script[type="application/json"]');
-    if (script === null)
-        return { status: 'invalid', reason: 'slot has no application/json config' };
-    const text = script.textContent ?? '';
-    if (text.trim() === '')
-        return { status: 'invalid', reason: 'slot config is empty' };
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch (error) {
-        const detail = error instanceof Error && error.message !== '' ? error.message : 'invalid JSON';
-        return { status: 'invalid', reason: `slot config is not valid JSON: ${detail}` };
-    }
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        return { status: 'invalid', reason: 'slot config must be a JSON object' };
-    }
-    return { status: 'ok', config: parsed };
-}
-/**
- * The slot id the host addressed this element by — the key `respond()` takes. Absent on a
- * display-only slot, which has no id and produces no response.
- */
-export function readSlotId(element) {
-    const id = element.getAttribute('slot-id')?.trim();
-    return id === undefined || id === '' ? undefined : id;
-}

package/dist/pages/types.d.ts

@@ -1,98 +0,0 @@
-/**
- * The response contract the page bundle produces, as plain browser-safe types.
- *
- * These mirror `src/core/human/page-schema.ts` field-for-field — `commentSchema`,
- * `commentAnchorSchema`, and the four `*ResponseSchema`s — and are deliberately a
- * separate declaration rather than an import: nothing under `src/pages/` may reach
- * a runtime package (zod) or a module outside this directory, because the bundle is
- * a browser IIFE. The schemas remain the source of truth; a change there is a change
- * that must land here in the same commit.
- *
- * Two rules the shapes are built around:
- *
- *  1. **One comment shape everywhere.** Every response-bearing element carries
- *     comments, and every comment is `{ id, anchor, text }`. A comment on an option,
- *     a table row, a card, or a range of prose differs only in its `anchor`.
- *  2. **Selection is ids, never indexes or values.** The agent authored the ids it is
- *     asking about, so the response keys straight off them.
- *
- * Config types are NOT here: a config is one element's private input, mirrored in that
- * element's own module. A response is what crosses `window.crtr.respond`, so it is
- * shared.
- */
-/** What a comment is attached to. One union across every element. */
-export type CommentAnchor = 
-/** The presented content as a whole. */
-{
-    kind: 'whole';
-}
-/** One option of an `options` element. */
- | {
-    kind: 'option';
-    optionId: string;
-}
-/** One row of a `table`. */
- | {
-    kind: 'row';
-    rowId: string;
-}
-/** One column of a `table`. */
- | {
-    kind: 'column';
-    columnId: string;
-}
-/** One card of a `cards` grid. */
- | {
-    kind: 'card';
-    cardId: string;
-}
-/**
- * A character range of a `text` element's final text, review-style. `quote` is the
- * text as it read when the comment was left, so the comment survives (readably) an
- * edit that moves the offsets.
- */
- | {
-    kind: 'range';
-    start: number;
-    end: number;
-    quote: string;
-};
-/** A user comment. The same shape in every element's response. */
-export type Comment = {
-    /** Stable per comment; frame-local, minted by `newCommentId()`. */
-    id: string;
-    anchor: CommentAnchor;
-    text: string;
-};
-/** `options` — single or multi select, per-option comments, optional freetext. */
-export type OptionsResponse = {
-    /** Always an array; a single-select answer is a one-element array. */
-    selectedOptionIds: string[];
-    comments: Comment[];
-    /** Present only when the config allows freetext and the user typed something. */
-    freetext?: string;
-};
-/** `text` — an edited draft and/or anchored comments on presented prose. */
-export type TextResponse = {
-    /** The text as the user is leaving it. */
-    text: string;
-    /** True once `text` differs from what the agent presented. */
-    edited: boolean;
-    comments: Comment[];
-};
-/** `table` — row and/or column selection with anchored comments. */
-export type TableResponse = {
-    selectedRowIds: string[];
-    selectedColumnIds: string[];
-    comments: Comment[];
-};
-/** `cards` — card selection with per-card comments. */
-export type CardsResponse = {
-    selectedCardIds: string[];
-    comments: Comment[];
-};
-/**
- * Any slot response. The open member covers a product-registered `unvalidated` slot,
- * whose shape only the product renderer knows.
- */
-export type SlotResponse = OptionsResponse | TextResponse | TableResponse | CardsResponse | Record<string, unknown>;

package/dist/pages/types.js

@@ -1,23 +0,0 @@
-/**
- * The response contract the page bundle produces, as plain browser-safe types.
- *
- * These mirror `src/core/human/page-schema.ts` field-for-field — `commentSchema`,
- * `commentAnchorSchema`, and the four `*ResponseSchema`s — and are deliberately a
- * separate declaration rather than an import: nothing under `src/pages/` may reach
- * a runtime package (zod) or a module outside this directory, because the bundle is
- * a browser IIFE. The schemas remain the source of truth; a change there is a change
- * that must land here in the same commit.
- *
- * Two rules the shapes are built around:
- *
- *  1. **One comment shape everywhere.** Every response-bearing element carries
- *     comments, and every comment is `{ id, anchor, text }`. A comment on an option,
- *     a table row, a card, or a range of prose differs only in its `anchor`.
- *  2. **Selection is ids, never indexes or values.** The agent authored the ids it is
- *     asking about, so the response keys straight off them.
- *
- * Config types are NOT here: a config is one element's private input, mirrored in that
- * element's own module. A response is what crosses `window.crtr.respond`, so it is
- * shared.
- */
-export {};