@jarenjs/studio 0.83.3 → 0.84.3

package/dist/types/component/shared/host-widget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file The shared host-widget lifecycle (the third studio forced the
+ * extraction): mount boots a nested app into the host node, update
+ * reboots ONLY when the document or its revision changed, unmount
+ * destroys. The `mount`/`update`/`unmount` trio was byte-identical
+ * between the Studio and Flow boundaries; the `destroy` halves
+ * differed DELIBERATELY (Studio reports teardown failures, Flow
+ * swallows them), so the factory takes both halves as parameters and
+ * reconciles nothing by averaging — one factory, three callers, each
+ * keeping its own policy.
+ */
+/**
+ * @param {{ boot: (handle: any, props: any) => void,
+ *   destroy: (handle: any) => void }} lifecycle
+ * @returns {{ mount: Function, update: Function, unmount: Function }}
+ */
+export declare function createHostWidget({ boot, destroy }: {
+    boot: (handle: any, props: any) => void;
+    destroy: (handle: any) => void;
+}): {
+    mount: Function;
+    update: Function;
+    unmount: Function;
+};

package/dist/types/component/shared/memo.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Single-entry memoization on argument identity. The viewModel wraps
+ * its derivations with this so an unchanged input slice returns the
+ * PREVIOUS node by reference — which makes the JSLT memo (and through
+ * it the renderer's === fast path) fire for the whole subtree.
+ * Only successful calls populate the memo; a throwing call keeps the
+ * previous successful entry available.
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn
+ * @returns {F}
+ */
+export declare function memo1<F extends (...args: any[]) => any>(fn: F): F;

package/dist/types/component/shared/nodes.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Builders for the kind-tagged render-node vocabulary. Boundaries emit
+ * these plain-JSON nodes; the 'ui' view mode renders each kind with one
+ * generic rule. This is the site's component library — as data.
+ */
+/** A paragraph of prose. */
+export declare const p: (text: any) => {
+    kind: string;
+    text: any;
+};
+/** A row of stat cards. */
+export declare const cards: (items: any) => {
+    kind: string;
+    items: any;
+};
+/** A titled table; rows are `{ cells: string[], strong?: boolean }`. */
+export declare const table: (title: any, head: any, rows: any, note: any) => {
+    kind: string;
+    title: any;
+    head: any;
+    note: any;
+    rows: any;
+};
+/** An informational block with an optional link button. */
+export declare const callout: (title: any, text: any, href: any, link: any) => {
+    kind: string;
+    title: any;
+    text: any;
+    href: any;
+    link: any;
+};
+/** A code block; `badge` renders next to the title. */
+export declare const code: (title: any, text: any, badge: any) => {
+    kind: string;
+    title: any;
+    text: any;
+    badge: any;
+};
+/**
+ * One error → one display string. Coded errors compose their own
+ * message (`code: reason at path` per the @jarenjs/core contract), so
+ * this never prefixes anything — prefixing again is how the same suite
+ * used to show one error two different ways on two pages.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export declare const errorMessage: (err: unknown) => string;
+/** An error block in the engine-error shape (code/docPath/dataPath/position). */
+export declare function error(err: any, fallbackTitle: any): {
+    kind: string;
+    title: any;
+    message: string;
+    detail: string | null;
+};
+/** A collapsible section of further nodes. */
+export declare const details: (summary: any, items: any) => {
+    kind: string;
+    summary: any;
+    items: any;
+};
+/** An SVG chart card: `vnode` is @jarenjs/charts' projection (charts
+ * carry their own internal title; `title` adds a card heading only when
+ * the SVG has none). */
+export declare const chart: (title: any, vnode: any, note: any) => {
+    kind: string;
+    title: any;
+    vnode: any;
+    note: any;
+};
+/**
+ * A rendered Markdown article: `vnode` is the @jarenjs/md component's
+ * projection, spliced in verbatim exactly as a chart's SVG is. The
+ * site's own sections are kind-nodes; a section a PACKAGE owns arrives
+ * as markdown, and this is the one node that carries it.
+ */
+export declare const article: (vnode: any) => {
+    kind: string;
+    vnode: any;
+};
+/** A live search input bound to the given action. */
+export declare const search: (action: any, value: any, placeholder: any) => {
+    kind: string;
+    action: any;
+    value: any;
+    placeholder: any;
+};
+/** A "show more" button bound to the given action. */
+export declare const more: (action: any, label: any) => {
+    kind: string;
+    action: any;
+    label: any;
+};

package/dist/types/component/shared/schema-options.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The validator options every surface uses when it compiles a schema
+ * the component ships — the engine grammars, the chart definition, the
+ * app meta-schema.
+ *
+ * `unknownFormats: 'error'` is the point of the file. `@jarenjs/validate`
+ * defaults to `'ignore'`, because the specification requires that an
+ * unknown `format` be treated as an annotation rather than an assertion
+ * failure, and a library has to be able to compile a stranger's schema.
+ * The component schemas are not a stranger's: a `format` in one of them names a
+ * check we intend to happen, so a name with no registered compiler is a
+ * missing `addFormats` call, and the alternative to failing is a keyword
+ * that silently validates everything. That is how the published grammars
+ * came to declare `format: "json-path"` for a long time without anything
+ * ever checking one.
+ *
+ * The line is deliberate and worth keeping: a schema the USER supplied —
+ * the validator playground's input, a project file in the studio — keeps
+ * the library default, because refusing to compile a stranger's valid
+ * schema over a format we happen not to implement would be our problem
+ * presented as theirs.
+ */
+/** Options for compiling a schema this project ships. */
+export declare const OUR_SCHEMA_OPTIONS: Readonly<{
+    skipErrors: false;
+    collectErrors: true;
+    unknownFormats: 'error';
+}>;

package/dist/types/component/shared/studio-kit.d.ts

@@ -0,0 +1,78 @@
+/** Shared editor controls and accessible phone pane switching. */
+/**
+ * The editor textarea; live buffers publish input before unrelated renders.
+ * @param {{ value: string, action: string, rows?: number,
+ *   readonly?: boolean, live?: boolean }} options
+ */
+export declare function editorTextarea(options: {
+    value: string;
+    action: string;
+    rows?: number;
+    readonly?: boolean;
+    live?: boolean;
+}): (string | {
+    class: string;
+    rows: number;
+    spellcheck: string;
+    value: string;
+    readonly?: string | undefined;
+    on: {
+        change: string;
+        input?: string | undefined;
+    };
+})[];
+/**
+ * The error line.
+ * @param {any} content - a query expression or literal text
+ */
+export declare function errorLine(content: any): any[];
+/**
+ * The phone pane switcher — a segmented bar that shows ONE pane at a
+ * time below the breakpoint, the pattern `@jarenjs/play` established.
+ *
+ * The protocol is three parts, and every surface implements all three:
+ * the pane container carries `data-pane` (the live pane id), this bar
+ * carries the studio's own `-panebar` class plus the shared `seg`
+ * control classes, and the studio's stylesheet hides the unselected
+ * panes inside its `@media (max-width: 1024px)` block. Switching is a
+ * SINGLE attribute write on the container — the panes stay mounted, so
+ * a hidden editor keeps its caret, its scroll and its undo stack, and
+ * nothing re-renders but the bar's two changed buttons.
+ *
+ * The segments are toggle buttons in a group, not a `tablist`: a pane
+ * is a grid area, not a `tabpanel`, so `aria-pressed` states the truth
+ * that `aria-selected` would overclaim.
+ *
+ * @param {{ pane: string, action: string, class: string,
+ *   panes: [string, string][] }} options - `pane` is the query
+ *   expression holding the live pane id, `panes` the `[id, label]`
+ *   pairs in bar order
+ */
+export declare function paneSwitcher(options: {
+    pane: string;
+    action: string;
+    class: string;
+    panes: [string, string][];
+}): (string | (string | {
+    type: string;
+    class: {
+        $if: (string | {
+            $eq: string[];
+        })[];
+    };
+    'aria-pressed': {
+        $if: (string | {
+            $eq: string[];
+        })[];
+    };
+    on: {
+        click: {
+            action: string;
+            with: string;
+        };
+    };
+})[] | {
+    class: string;
+    role: string;
+    'aria-label': string;
+})[];

package/dist/types/component/shared/ui.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The generic render-node vocabulary — mode 'ui'. Boundaries (and the
+ * docs content) emit kind-tagged JSON nodes; one rule per kind turns
+ * them into vnodes. This is the site's component library, as data:
+ * cards, tables, callouts, code blocks, error blocks, bar charts,
+ * collapsibles, rendered Markdown articles, a search box and a
+ * show-more button.
+ */
+/**
+ * The rule for one deep-linkable tab in a `nav.tabs` strip. Each page
+ * holds its tab entries (`{ href, label, active }`) at a different
+ * location, hence the match parameter.
+ * @param {string} match - the JSONPath to the tab entries.
+ * @param {string} mode - the page's dispatch mode.
+ */
+export declare const tabRule: (match: string, mode: string) => {
+    match: string;
+    mode: string;
+    body: (string | {
+        href: string;
+        class: {
+            $if: string[];
+        };
+    })[];
+};
+export declare const UI_RULES: ({
+    match: string;
+    mode: string;
+    body: (string | {}[] | (string | {}[] | {
+        class: string;
+    })[] | {
+        class: string;
+        $if?: undefined;
+    } | {
+        $if: (string | (string | {
+            class: string;
+        })[])[];
+        class?: undefined;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: {}[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        $apply: string;
+    }[] | {
+        class: {
+            $if: string[];
+        };
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {}[] | {
+        class: string;
+        $if?: undefined;
+    } | {
+        $if: (string | (string | {
+            href: string;
+            class: string;
+        })[])[];
+        class?: undefined;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | (string | {}[] | {
+        class: string;
+    })[] | {
+        class: string;
+        $if?: undefined;
+    } | {
+        $if: ((string | {
+            class: string;
+            $if?: undefined;
+        } | {
+            $if: (string | (string | {
+                class: string;
+            })[])[];
+            class?: undefined;
+        })[] | {
+            $or: string[];
+        })[];
+        class?: undefined;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {}[] | {
+        $apply: string;
+    }[] | {
+        class: string;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        class: string;
+        $if?: undefined;
+    } | {
+        $if: (string | {}[])[];
+        class?: undefined;
+    } | {
+        $if: (string | (string | {
+            class: string;
+        })[])[];
+        class?: undefined;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        type: string;
+        class: string;
+        placeholder: string;
+        value: string;
+        on: {
+            input: string;
+        };
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | (string | {
+        type: string;
+        class: string;
+        on: {
+            click: string;
+        };
+    })[] | {
+        class: string;
+    })[];
+})[];

package/dist/types/component/view.d.ts

@@ -73,13 +73,12 @@ export declare const projectRules: ({
         class: string;
         $if?: undefined;
     } | {
-        class?: undefined;
         $if: (string | (string | {
             class: string;
             role: string;
         })[])[];
-    } | {
         class?: undefined;
+    } | {
         $if: ((string | (string | {
             name: {
                 $default: string[];
@@ -88,12 +87,12 @@ export declare const projectRules: ({
         })[] | {
             class: string;
         })[] | {
-            $if?: undefined;
             $eq: string[];
+            $if?: undefined;
         } | {
             $if: ({
-                $if?: undefined;
                 $eq: string[];
+                $if?: undefined;
             } | {
                 $eq?: undefined;
                 $if: (string | (string | {
@@ -111,6 +110,7 @@ export declare const projectRules: ({
             })[];
             $eq?: undefined;
         })[];
+        class?: undefined;
     })[] | (string | (string | {
         class: string;
         type: string;
@@ -233,7 +233,6 @@ export declare const projectRules: ({
     })[] | (string | {
         class: string;
     })[] | {
-        $if?: undefined;
         type: string;
         class: {
             $if: string[];
@@ -245,15 +244,16 @@ export declare const projectRules: ({
                 with: string;
             };
         };
+        $if?: undefined;
     } | {
         type?: undefined;
-        class?: undefined;
         title?: undefined;
         on?: undefined;
         $if: (string | (string | {
             class: string;
             title: string;
         })[])[];
+        class?: undefined;
     })[] | {
         class: string;
     })[];

package/dist/types/data/boot-stages.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file The data studio's boot as a closed, finite protocol. A browser
+ * store boots through five stages — the worker starting, the SQLite
+ * wasm build initializing, the OPFS pool being acquired, the topology
+ * being decided, the first store open — and every one of them finishes
+ * as a success or as a STABLE, NAMED failure: `{ code: 'DATA_BOOT',
+ * stage, message }`. An outer deadline can say only that something
+ * stopped; a named stage says which resource must be released and what
+ * a consumer can report. So each stage carries its own budget, a stage
+ * that overruns it fails under its own name, and a stage that settles
+ * late changes nothing.
+ *
+ * This module is the pure half: the stage names, the budgets, the error
+ * shape and the runner that attaches a timer to a stage and clears it
+ * on either outcome. The page's transport and the worker announce their
+ * stages through it; the browser-shaped work (a `Worker`, a
+ * `BroadcastChannel`, the wasm module) stays in the boundary and the
+ * worker, where Node cannot follow — which is why the runner takes its
+ * timers as an injection and a test drives it with millisecond budgets.
+ */
+/** The five stages, in the order a boot passes through them. */
+export declare const BOOT_STAGES: readonly string[];
+/** The code every boot failure carries, whatever its stage. */
+export declare const BOOT_ERROR_CODE = "DATA_BOOT";
+/**
+ * The production budgets, in milliseconds: the wasm build and the first
+ * store open are real work and get room; the pool install is bounded
+ * where an engine has been seen never to settle it; a topology decision
+ * is a lock probe or a ping window.
+ * @type {Readonly<Record<string, number>>}
+ */
+export declare const DEFAULT_BOOT_BUDGETS: Readonly<Record<string, number>>;
+/**
+ * The one failure shape a boot can end in: the stage that failed, the
+ * cause's message, and the fixed code.
+ */
+export declare class DataBootError extends Error {
+    /** @type {typeof BOOT_ERROR_CODE} */
+    code: typeof BOOT_ERROR_CODE;
+    /** @type {string} */
+    stage: string;
+    /**
+     * @param {string} stage - one of {@link BOOT_STAGES}
+     * @param {string} message - what happened, for a person
+     * @param {unknown} [cause]
+     */
+    constructor(stage: string, message: string, cause?: unknown);
+    /** The page-visible record: exactly `{ code, stage, message }`. */
+    toJSON(): {
+        code: "DATA_BOOT";
+        stage: string;
+        message: string;
+    };
+}
+/**
+ * Any failure as a boot failure under `stage`: a `DataBootError` keeps
+ * the stage it already names, anything else is wrapped with its message.
+ * @param {string} stage
+ * @param {unknown} error
+ * @returns {DataBootError}
+ */
+export declare function bootFailure(stage: string, error: unknown): DataBootError;
+/**
+ * Resolve the budgets a boot runs under: the defaults, overridden per
+ * stage by a positive finite number; anything else is ignored rather than
+ * turned into a zero budget nobody meant.
+ * @param {unknown} overrides - a partial `{ stage: ms }` record, or not
+ * @returns {Readonly<Record<string, number>>}
+ */
+export declare function resolveBootBudgets(overrides: unknown): Readonly<Record<string, number>>;
+/**
+ * The stage runner. `run(stage, work)` starts `stage`'s timer, calls
+ * `work(advance)` and settles ONCE: with the work's value, with the
+ * work's failure named under the stage current at that moment, or —
+ * when the current stage's budget runs out first — with a
+ * `DataBootError` naming that stage. `advance(next)` moves the run to
+ * a later stage: the previous timer is cleared and the next stage's
+ * budget starts, so a multi-stage piece of work (the worker's init,
+ * which announces its stages as it passes them) is bounded per stage
+ * from the page. The timer is cleared on every outcome, and a late
+ * settlement after a timeout is dropped: the failure a consumer saw is
+ * the failure it keeps.
+ *
+ * @param {{ budgets?: Readonly<Record<string, number>>,
+ *   setTimer?: (fn: () => void, ms: number) => any,
+ *   clearTimer?: (handle: any) => void }} [options] - budgets per stage
+ *   and the timer pair (the platform's by default)
+ */
+export declare function createStageRunner(options?: {
+    budgets?: Readonly<Record<string, number>>;
+    setTimer?: (fn: () => void, ms: number) => any;
+    clearTimer?: (handle: any) => void;
+}): Readonly<{
+    run: (stage: string, work: (advance: (next: string) => void) => any) => Promise<any>;
+    budgets: Readonly<Record<string, number>>;
+    dispose: () => void;
+}>;

package/dist/types/data/browser-worker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The SQLite module is injected, like the handle consumed by @jarenjs/db/wasm.
+ * No package import or worker URL is chosen by this component.
+ * @param {{ initialize: () => Promise<any>, scope: any, createChannel: (name: string) => any,
+ *   identity: { channel: string, pool: string, database: string, snapshots: string, lock: string }, operators?: any }} env
+ * @returns {{ dispose: () => Promise<void> }}
+ */
+export declare function createBrowserDataWorker(env: {
+    initialize: () => Promise<any>;
+    scope: any;
+    createChannel: (name: string) => any;
+    identity: {
+        channel: string;
+        pool: string;
+        database: string;
+        snapshots: string;
+        lock: string;
+    };
+    operators?: any;
+}): {
+    dispose: () => Promise<void>;
+};

package/dist/types/data/contract.d.ts

@@ -0,0 +1,9 @@
+import { compileContract } from '@jarenjs/contract';
+/** @type {ReturnType<typeof compileContract>} */
+export declare const dataContract: ReturnType<typeof compileContract>;
+/** @type {{ $contract: string, id: string, operations: Record<string, object> } & Record<string, unknown>} */
+export declare const dataContractDocument: {
+    $contract: string;
+    id: string;
+    operations: Record<string, object>;
+} & Record<string, unknown>;

package/dist/types/data/editor.d.ts

@@ -0,0 +1,81 @@
+export type DataSnapshot = {
+    document: {
+        model: any;
+        query: any;
+    };
+    buffers: {
+        modelText: string;
+        queryText: string;
+    };
+    revision: string;
+    result: any;
+    explain: any;
+};
+export type EditorReceipt = {
+    ok: boolean;
+    document?: any;
+    revision?: string;
+    conflict?: boolean;
+    error?: string;
+    errors?: any[];
+    valid?: boolean;
+    total?: number;
+    code?: string;
+    result?: any;
+    explain?: any;
+    model?: any;
+};
+import { applyJSONPatch } from '@jarenjs/json/patch';
+/** @param {{ getApp: () => any, runtime: any, operators?: { toOptions: () => any } }} env */
+export declare function createDataController(env: {
+    getApp: () => any;
+    runtime: any;
+    operators?: {
+        toOptions: () => any;
+    };
+}): {
+    read: () => DataSnapshot;
+    validate: (candidate: {
+        model: any;
+        query: any;
+    }) => {
+        valid: boolean;
+        total: number;
+        errors: {
+            code: string | null;
+            message: string;
+            docPath?: string;
+            member: string;
+        }[];
+    } | {
+        valid: boolean;
+        total: number;
+        errors: {
+            code: any;
+            message: any;
+        }[];
+    };
+    replace: (candidate: {
+        model: any;
+        query: any;
+    }, options?: {
+        expectedRevision?: string;
+    }) => Promise<EditorReceipt>;
+    apply: (patch: Parameters<typeof applyJSONPatch>[1], options?: {
+        expectedRevision?: string;
+    }) => Promise<EditorReceipt>;
+    run: (options?: {
+        operation?: 'query' | 'open';
+        externals?: Record<string, any>;
+    }) => Promise<EditorReceipt>;
+    subscribe: (listener: (snapshot: DataSnapshot) => void) => () => void;
+    attach: () => void;
+    effects: {
+        'data-accepted': (id: any) => void;
+        'data-refused': (id: any) => void;
+        'data-editor-run': ((props: any, dispatch: any) => Promise<void>) & {
+            dispose: () => void;
+        };
+    };
+    dispose: () => void;
+};