@lloyal-labs/ui 0.1.0-alpha.10

package/dist/prose.js

@@ -0,0 +1,176 @@
+/**
+ * The headings, links and heading ids of a markdown body, read with the grammar
+ * that renders it. `Markdown` draws prose through remark; what a view derives
+ * from the same prose — an outline, citation chips, the id a heading is given —
+ * comes from the same parser, so what the outline names is what the page shows,
+ * by construction: a heading's `text` here is the string its rendered element
+ * contains, inline markup and all resolved.
+ *
+ * Two grammars are used on purpose, split by concern. Headings and links
+ * (`headingsOf`, `linksOf`) come from remark, memoized, and parsed in the two
+ * pieces the streaming view renders — the finished blocks and the block under
+ * the caret — so a fact read per token costs one block's parse. The
+ * streaming boundary (`splitStreaming`) comes from marked's block lexer, which
+ * runs on every token over the whole buffer and is fifteen times cheaper — and
+ * a boundary it misjudges costs one extra parse of one block, never a wrong
+ * document, so it need not agree with the renderer to the byte.
+ *
+ * Framework-free: a node script, the Ink view and the browser page read the
+ * same headings and links.
+ *
+ * @packageDocumentation
+ * @category UI
+ */
+import { lexer } from 'marked';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import { toString } from 'mdast-util-to-string';
+/** The url schemes a link may carry: react-markdown's own rule (micromark's `sanitizeUri` without the encode
+ *  step — https://github.com/remarkjs/react-markdown, `defaultUrlTransform`), restated here because that module
+ *  imports React at scope and this one is framework-free. */
+const SAFE_PROTOCOL = /^(https?|ircs?|mailto|xmpp)$/i;
+/** The ONE url policy of a harness view: the content plane's scheme (`attachment://…`) is admitted, a relative
+ *  url or a safe scheme passes, anything else (`javascript:`, `data:`) is stripped to `''`. `Markdown` renders
+ *  through it and `linksOf` reports through it, so a citation built from a link carries the href the page
+ *  carries. */
+export function admitUrl(url) {
+    if (url.startsWith('attachment://'))
+        return url;
+    const colon = url.indexOf(':');
+    const questionMark = url.indexOf('?');
+    const numberSign = url.indexOf('#');
+    const slash = url.indexOf('/');
+    if (colon === -1 || // no protocol: relative
+        (slash !== -1 && colon > slash) || // the first colon is not a protocol's
+        (questionMark !== -1 && colon > questionMark) ||
+        (numberSign !== -1 && colon > numberSign) ||
+        SAFE_PROTOCOL.test(url.slice(0, colon)))
+        return url;
+    return '';
+}
+/** The renderer's grammar, exactly: `Markdown` parses with these two plugins, so a `$…$` span is math here as
+ *  it is there, never emphasis. */
+const parser = unified().use(remarkParse).use(remarkGfm).use(remarkMath);
+/** Parsed texts, most recent last. A body is parsed in two pieces (see {@link nodesOf}), and a canvas reads the
+ *  settled body, its exchanges and the sections in one pass, so a small memo would thrash; an unbounded one
+ *  would pin every body a session ever showed. */
+const parsed = new Map();
+const KEEP = 32;
+function rootOf(markdown) {
+    const hit = parsed.get(markdown);
+    if (hit) {
+        parsed.delete(markdown);
+        parsed.set(markdown, hit);
+        return hit;
+    }
+    const root = parser.parse(markdown);
+    parsed.set(markdown, root);
+    if (parsed.size > KEEP)
+        parsed.delete(parsed.keys().next().value);
+    return root;
+}
+function* walk(nodes) {
+    for (const node of nodes) {
+        yield node;
+        if ('children' in node && Array.isArray(node.children))
+            yield* walk(node.children);
+    }
+}
+/** Every node of a body with where it starts, parsed the way the streaming view renders it: the finished
+ *  blocks as one piece, kept while they stand, and the block under the caret as another, parsed fresh. A fact
+ *  read per token — the outline of a section as it streams — then costs one block's parse, not the body's;
+ *  and a settled body costs its parse once. The pieces are {@link splitStreaming}'s, so a body it refuses to
+ *  split (a reference definition, display math) is one piece, and no block is ever read across the seam. The
+ *  offsets count into the body with its line endings normalised to `\n`, as the split normalises them. */
+function* nodesOf(markdown) {
+    const { head, tail } = splitStreaming(markdown);
+    for (const node of walk(rootOf(head).children))
+        yield { node, offset: node.position?.start.offset ?? 0 };
+    for (const node of walk(rootOf(tail).children))
+        yield { node, offset: head.length + (node.position?.start.offset ?? 0) };
+}
+/** Every heading in document order. */
+export function headingsOf(markdown) {
+    const out = [];
+    for (const { node, offset } of nodesOf(markdown)) {
+        if (node.type === 'heading')
+            out.push({ depth: node.depth, text: toString(node), offset });
+    }
+    return out;
+}
+/** Every link in document order, as the renderer draws them: inline links, the bare urls GFM links, and
+ *  reference-style links resolved through their definitions — the FIRST definition of an identifier, as
+ *  CommonMark resolves it (an unresolved reference renders as text and is not a link). Each href has passed
+ *  {@link admitUrl}, so a link whose scheme the renderer strips is reported with the same empty href. */
+export function linksOf(markdown) {
+    const definitions = new Map();
+    for (const { node } of nodesOf(markdown)) {
+        if (node.type === 'definition' && !definitions.has(node.identifier))
+            definitions.set(node.identifier, node.url);
+    }
+    const out = [];
+    for (const { node, offset } of nodesOf(markdown)) {
+        if (node.type === 'link')
+            out.push({ href: admitUrl(node.url), text: toString(node), offset });
+        else if (node.type === 'linkReference') {
+            const href = definitions.get(node.identifier);
+            if (href !== undefined)
+                out.push({ href: admitUrl(href), text: toString(node), offset });
+        }
+    }
+    return out;
+}
+const slugify = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'h';
+/** The id each heading is given under `prefix`, in document order — the ONE derivation, so an outline that
+ *  names an anchor and the prose that carries it cannot disagree. A repeated heading is numbered from its
+ *  second appearance, and the number is taken against the ids already given out, not the slug's count: `A`,
+ *  `A`, `A-2` become `a`, `a-2`, `a-2-2`, never two `a-2`s. A renderer assigns these to its heading elements
+ *  in the same order. */
+export function anchorsOf(headings, prefix) {
+    const given = new Set();
+    return headings.map((h) => {
+        const base = `${prefix}-${slugify(h.text)}`;
+        let anchor = base;
+        for (let n = 2; given.has(anchor); n++)
+            anchor = `${base}-${n}`;
+        given.add(anchor);
+        return { anchor, text: h.text, depth: h.depth };
+    });
+}
+/** Where streaming prose stops being finished. Everything up to the last block CommonMark recognises is
+ *  complete, parsed once and kept while it stands; the last block is the one still being written, parsed per
+ *  token. The boundaries are marked's — a spec-tested block tokenizer, used here only to find where the last
+ *  block starts: a loose list is one block, a fence owns its blank lines. A block boundary this misjudges
+ *  would cost one extra parse of one block, never a wrong document — except for two constructs marked does not
+ *  see the way the renderer does, where the split is refused and the whole buffer is the tail:
+ *  - a reference definition (anywhere, a blockquote included) resolves links in EARLIER blocks, so a head
+ *    rendered without it would show those references as text;
+ *  - a display equation (`$$…$$`) may span a blank line, which marked reads as a block boundary; cut there,
+ *    the renderer would draw an equation, a paragraph and an empty equation — and nothing short of the
+ *    renderer's grammar can say where one opens (a `$$` in inline code is not a delimiter; `$$$$` is).
+ *  A document that carries either is rendered whole: the split is refused for the document's whole life, and
+ *  the cost of that is paid only by documents with display math or reference definitions. */
+export function splitStreaming(markdown) {
+    // marked reports raw text with line endings normalised; normalise first so head + tail is the text parsed.
+    const text = markdown.replace(/\r\n?/g, '\n');
+    const tokens = lexer(text);
+    if (tokens.length < 2 || text.includes('$$') || hasDefinition(tokens))
+        return { head: '', tail: text };
+    const cut = text.length - tokens[tokens.length - 1].raw.length;
+    return { head: text.slice(0, cut), tail: text.slice(cut) };
+}
+/** A reference definition at any depth of marked's token tree — a blockquote or list nests its own. */
+function hasDefinition(tokens) {
+    for (const t of tokens) {
+        if (t.type === 'def')
+            return true;
+        if (t.tokens && hasDefinition(t.tokens))
+            return true;
+        if (t.items && hasDefinition(t.items))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=prose.js.map

package/dist/prose.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,43 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { Availability, Bridge, Projection, WireStatus } from '@lloyal-labs/binding';
+export interface Harness<E, C, S extends object> {
+    bridge: Bridge<E, C, S>;
+    projection: Projection<S>;
+}
+/** The one projection over a bridge — the provider's, shared with a consumer outside React (a history adapter). */
+export declare function projectionFor<E, C, S extends object>(bridge: Bridge<E, C, S>, initialState: S, reduce: (state: S, ev: E) => S): Projection<S>;
+export declare function HarnessProvider<E, C, S extends object>({ bridge, initialState, reduce, children }: {
+    bridge: Bridge<E, C, S>;
+    initialState: S;
+    reduce: (state: S, ev: E) => S;
+    children: ReactNode;
+}): ReactElement;
+/** The provider's bridge and projection, for a consumer outside the hooks (a history adapter). */
+export declare function useHarness<E = unknown, C = unknown, S extends object = object>(): Harness<E, C, S>;
+/** Read a derivation of the folded state, memoized per fold. */
+export declare function useProjection<S extends object, T>(select: (state: S) => T): T;
+/** Dispatch a command to the harness. */
+export declare function useSend<C>(): (command: C) => void;
+/** The wire's status. A bridge without `onStatus` (in-process) reads 'connected' forever. */
+export declare function useConnection(): WireStatus;
+/**
+ * Whether this harness can take work, and if not, why — the question a view actually asks.
+ *
+ * Derived from the transport's status and the host's session phase, because neither answers it
+ * alone: a queued reader's socket is healthy, and an ended session is followed by a close that
+ * reads as a network failure. Prefer this to {@link useConnection}, which is the transport fact
+ * on its own.
+ */
+export declare function useAvailability(): Availability;
+/**
+ * Ask the placement for a working harness — or null where this bridge cannot provide one.
+ *
+ * A view knows WHEN recovery is wanted and never what it costs: a browser opens a new connection
+ * because a served host cannot re-admit an existing one; a desktop shell starts a new engine while
+ * its renderer's IPC link stays up throughout. Same button, different price, and the view pays
+ * neither.
+ */
+export declare function useRecover(): (() => void) | null;
+/** The content plane's origin, or null on a bridge without one. */
+export declare function useContentOrigin(): string | null;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAgB,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvG,MAAM,WAAW,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM;IAC7C,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC3B;AASD,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAO7I;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAClG,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,YAAY,EAAE,CAAC,CAAC;IAChB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAGf;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAIlG;AAID,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAc7E;AAED,yCAAyC;AACzC,wBAAgB,OAAO,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAGjD;AAqCD,6FAA6F;AAC7F,wBAAgB,aAAa,IAAI,UAAU,CAI1C;AA4CD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAI9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAGhD;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAGhD"}

package/dist/provider.js

@@ -0,0 +1,172 @@
+/**
+ * The projection, in React: a provider that connects a bridge once, and hooks
+ * that read the fold, the wire's status, the command sink and the content
+ * plane's origin. One projection per provider; a remount under the same bridge
+ * reattaches to the running fold, it never re-subscribes or resets.
+ *
+ * `useProjection(select)` memoizes per fold: the state is immutable between
+ * events, so a named selector returns the SAME reference until the next fold —
+ * what `useSyncExternalStore` needs. The contract: a selector with a stable
+ * identity may build objects; an inline selector must return a primitive.
+ *
+ * The folded state must be an OBJECT, and a new one on every event. Both halves
+ * are load-bearing and neither is a style preference: the memo is a `WeakMap`
+ * keyed by the snapshot, so a scalar or `null` state is not a legal key at all,
+ * and a state mutated in place keeps its identity and so keeps returning the
+ * selection cached against the previous fold. `S extends object` states the
+ * first half to the compiler. The second is a discipline the type system cannot
+ * carry, which is why it is written here.
+ *
+ * @category UI
+ */
+import { createContext, createElement, useContext, useMemo, useSyncExternalStore } from 'react';
+import { connectProjection, availabilityOf } from '@lloyal-labs/binding';
+// `object`, not `unknown`, is what the erased context can say now that `S` is
+// constrained — the hooks below cast back out of it exactly as before.
+const HarnessContext = createContext(null);
+/** One projection per bridge, for the life of the page: a React remount under the same bridge reattaches. */
+const projections = new WeakMap();
+/** The one projection over a bridge — the provider's, shared with a consumer outside React (a history adapter). */
+export function projectionFor(bridge, initialState, reduce) {
+    let projection = projections.get(bridge);
+    if (!projection) {
+        projection = connectProjection(bridge, initialState, reduce);
+        projections.set(bridge, projection);
+    }
+    return projection;
+}
+export function HarnessProvider({ bridge, initialState, reduce, children }) {
+    const value = useMemo(() => ({ bridge, projection: projectionFor(bridge, initialState, reduce) }), [bridge]);
+    return createElement(HarnessContext.Provider, { value: value }, children);
+}
+/** The provider's bridge and projection, for a consumer outside the hooks (a history adapter). */
+export function useHarness() {
+    const h = useContext(HarnessContext);
+    if (!h)
+        throw new Error('useHarness: no HarnessProvider above this component');
+    return h;
+}
+const derived = new WeakMap();
+/** Read a derivation of the folded state, memoized per fold. */
+export function useProjection(select) {
+    const { projection } = useHarness();
+    const read = () => {
+        const state = projection.getSnapshot();
+        let memo = derived.get(state);
+        if (!memo) {
+            memo = new Map();
+            derived.set(state, memo);
+        }
+        const key = select;
+        if (!memo.has(key))
+            memo.set(key, select(state));
+        return memo.get(key);
+    };
+    return useSyncExternalStore(projection.subscribe, read, read);
+}
+/** Dispatch a command to the harness. */
+export function useSend() {
+    const { bridge } = useHarness();
+    return bridge.send;
+}
+/** One status per bridge, for the life of the page. React reads `getSnapshot`
+ *  during render, so the status it reads must outlive the render that reads it:
+ *  the bridge is told once, here, and every renderer of it shares that one
+ *  answer. A bridge without `onStatus` (in-process) never leaves 'connected'. */
+const statuses = new WeakMap();
+function statusFor(bridge) {
+    let store = statuses.get(bridge);
+    if (!store) {
+        let status = 'connected';
+        const listeners = new Set();
+        bridge.onStatus?.((next) => {
+            status = next;
+            for (const notify of listeners)
+                notify();
+        });
+        store = {
+            subscribe(notify) {
+                listeners.add(notify);
+                return () => { listeners.delete(notify); };
+            },
+            getSnapshot: () => status,
+        };
+        statuses.set(bridge, store);
+    }
+    return store;
+}
+/** The status a server render reads: no wire has been asked yet. */
+const connected = () => 'connected';
+/** The wire's status. A bridge without `onStatus` (in-process) reads 'connected' forever. */
+export function useConnection() {
+    const { bridge } = useHarness();
+    const wire = statusFor(bridge);
+    return useSyncExternalStore(wire.subscribe, wire.getSnapshot, connected);
+}
+/** One derivation per bridge, for the life of the page — the same reason the status has one. */
+const availabilities = new WeakMap();
+function availabilityFor(bridge) {
+    let store = availabilities.get(bridge);
+    if (!store) {
+        // A bridge with no droppable link is up, and one with no session plane has a single implicit
+        // session that is live: nothing queues it and nothing reaps it, so "waiting" and "ended" are not
+        // states it can be in. This is the ONE place a placement difference is stated; the derivation
+        // itself knows no placements.
+        let wire = 'connected';
+        let session = bridge.onSession ? null : { phase: 'live' };
+        let value = availabilityOf(session, wire);
+        const listeners = new Set();
+        const settle = () => {
+            const next = availabilityOf(session, wire);
+            if (next === value)
+                return;
+            value = next;
+            for (const notify of listeners)
+                notify();
+        };
+        bridge.onStatus?.((next) => { wire = next; settle(); });
+        bridge.onSession?.((next) => { session = next; settle(); });
+        store = {
+            subscribe(notify) {
+                listeners.add(notify);
+                return () => { listeners.delete(notify); };
+            },
+            getSnapshot: () => value,
+        };
+        availabilities.set(bridge, store);
+    }
+    return store;
+}
+/** What a server render reads: nothing has been asked of either plane yet. */
+const starting = () => 'connecting';
+/**
+ * Whether this harness can take work, and if not, why — the question a view actually asks.
+ *
+ * Derived from the transport's status and the host's session phase, because neither answers it
+ * alone: a queued reader's socket is healthy, and an ended session is followed by a close that
+ * reads as a network failure. Prefer this to {@link useConnection}, which is the transport fact
+ * on its own.
+ */
+export function useAvailability() {
+    const { bridge } = useHarness();
+    const store = availabilityFor(bridge);
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, starting);
+}
+/**
+ * Ask the placement for a working harness — or null where this bridge cannot provide one.
+ *
+ * A view knows WHEN recovery is wanted and never what it costs: a browser opens a new connection
+ * because a served host cannot re-admit an existing one; a desktop shell starts a new engine while
+ * its renderer's IPC link stays up throughout. Same button, different price, and the view pays
+ * neither.
+ */
+export function useRecover() {
+    const { bridge } = useHarness();
+    return useMemo(() => (bridge.recover ? () => bridge.recover() : null), [bridge]);
+}
+/** The content plane's origin, or null on a bridge without one. */
+export function useContentOrigin() {
+    const { bridge } = useHarness();
+    return bridge.contentOrigin?.() ?? null;
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lloyal-labs/ui",
+  "version": "0.1.0-alpha.10",
+  "description": "The view side of a harness: the projection provider and hooks over a bridge, the generic agent fold, and the prose and figure primitives",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fold": {
+      "types": "./dist/fold.d.ts",
+      "default": "./dist/fold.js"
+    },
+    "./prose": {
+      "types": "./dist/prose.d.ts",
+      "default": "./dist/prose.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lloyal-ai/hdk.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/lloyal-ai/hdk/tree/main/packages/ui#readme",
+  "bugs": {
+    "url": "https://github.com/lloyal-ai/hdk/issues"
+  },
+  "keywords": [
+    "ui",
+    "react",
+    "harness",
+    "projection",
+    "markdown"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "dist/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@lloyal-labs/binding": "0.2.0-alpha.6",
+    "@lloyal-labs/media": "0.2.0-alpha.6",
+    "@types/mdast": "^4.0.4",
+    "katex": "^0.16.22",
+    "marked": "^18.0.13",
+    "mdast-util-to-string": "^4.0.0",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0"
+  }
+}