dsh-model-everything 0.5.2 → 0.6.1

package/lib/types/annotation.d.ts

@@ -0,0 +1,128 @@
+/**
+ * An annotation: the reader points at a node in a drawing and says something about it.
+ *
+ * The note has to reach the session as an ordinary message, because the session log is the only record a
+ * replay, a fork or a resumed agent can rebuild from. Two transports can carry it, and they consume the
+ * same text: a host command that turns the note into a follow-up (planned; the interface is
+ * `annotationMessage`), and the composer, which hands the text to the reader's own input box (works today).
+ *
+ * Splitting the text from the transport is what keeps the two interchangeable, and what lets this module be
+ * tested without a browser.
+ */
+/** What the reader said, and where. */
+export interface Annotation {
+    /** The node's id, as it appears in the markup the renderer wrote. */
+    nodeId: string;
+    /** The node's label, when it differs from the id: a reader points at words, not at identifiers. */
+    label?: string;
+    /** The note itself. Empty is meaningful: the reader marked the node and said nothing. */
+    note?: string;
+    /** Which drawing, when the reader is looking at more than one. A single source line is enough. */
+    caption?: string;
+}
+/**
+ * The text that travels to the session: what was marked, and what was said, and nothing invented.
+ *
+ * A blank note is not dropped - it says the node was marked - because "the reader pointed here" and "the
+ * reader pointed here and said this" are different messages, and only one of them survives a silent trim.
+ */
+/**
+ * The text that travels to the session: what was marked, what was said, and nothing invented.
+ *
+ * One message for N notes, with a fixed opening so both the reader and the model know what they are looking
+ * at: a note arrives without the picture, so the block says what it is about, which drawing, and that every
+ * numbered item is a separate answer. The shape follows the annotation plugin this harness already ships -
+ * an opening sentence, numbered items, a question line - and it stays English: this is protocol between
+ * reader and model, not interface chrome that follows the page's language.
+ *
+ * Plain lines, not a markdown quote: the reader's bubble is rendered as one text node, so a quote never
+ * becomes a quote there - it would only show its own `>` characters. The bubble is folded afterwards.
+ * A blank note is not dropped: 'marked, no note' and 'marked with this note' are different messages.
+ */
+export declare function annotationBlock(annotations: Annotation[]): string;
+/** One annotation, in the same block shape: a caller with a single note should not get a second format. */
+export declare function annotationMessage(annotation: Annotation): string;
+/** The parts of the page this module touches, so the client bundle needs no DOM lib and a test can fake them. */
+export interface ElementLike {
+    value?: unknown;
+    querySelector?: (selector: string) => unknown;
+    textContent?: unknown;
+    focus?: () => void;
+    dispatchEvent?: (event: unknown) => boolean;
+    getAttribute?: (name: string) => string | null;
+    tagName?: unknown;
+}
+export interface DocumentLike {
+    querySelector: (selector: string) => unknown;
+    querySelectorAll?: (selector: string) => ArrayLike<unknown>;
+}
+export declare function findComposer(doc: DocumentLike | undefined): ElementLike | undefined;
+/**
+ * What the page has, for a status line: a probe with no console needs one place to report from.
+ *
+ * Counts only. A reader's draft is never read into the report.
+ */
+export declare function pageCensus(doc: DocumentLike | undefined): string;
+/** What a write did, so the caller can say something true instead of something hopeful. */
+export type Placed = 'filled' | 'no-composer';
+/**
+ * Add the text to the composer, above whatever the reader has already typed.
+ *
+ * Appending rather than replacing is the only behavior that cannot lose work: a reader who was halfway
+ * through a message and clicked an annotation should find both halves in the box, not the annotation alone.
+ */
+export declare function fillComposer(doc: DocumentLike | undefined, text: string): Placed;
+/** Whether the page can take a Return key for the composer at all, so a button may promise it. */
+export declare function submitComposer(doc: DocumentLike | undefined): boolean;
+/**
+ * One note, two actions.
+ *
+ * Returns the sentence to show the reader: `sent` and `the box was not there` are different outcomes, and a
+ * button that reports the wrong one is worse than no button. The text is appended above a half-written draft,
+ * never in place of it.
+ */
+export declare function pushNote(document: DocumentLike | undefined, picked: {
+    id: string;
+} | null, note: string, caption: string, submit: boolean): string;
+/**
+ * The session a page is showing, read from its own address.
+ *
+ * The client services expose no "current session", and a slot's props are not guaranteed to carry one, but the
+ * page has to name the session in its URL to survive a reload - so the address is the one source that is always
+ * there. Both spellings are accepted: the `session-<uuid>` id this Harness mints and a bare uuid.
+ */
+export declare function sessionFromLocation(location: {
+    pathname?: string;
+    search?: string;
+    hash?: string;
+} | undefined): string | undefined;
+/**
+ * Put a whole annotation block in the composer, and say what happened.
+ *
+ * The block is one message for N notes: the model is told to answer each item, and the reader's input box sees
+ * the structured text rather than N raw fragments. The same failure vocabulary as a single note.
+ */
+export declare function pushBlock(document: DocumentLike | undefined, annotations: Annotation[], caption: string, submit: boolean): string;
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Where the reader's input box is, for a widget that has to sit right above it. */
+export declare function composerRect(doc: DocumentLike | undefined): Rect | undefined;
+/**
+ * Put the block above what the reader has already typed, and say what happened.
+ *
+ * Above, because the annotations introduce the message: the reader's own words are the point, and a block
+ * appended after them reads as an afterthought. A rich editor has no portable way to insert at the start, so
+ * it takes the same path as an empty box - the block becomes the message and the reader's text follows it.
+ */
+export declare function prependBlock(document: DocumentLike | undefined, annotations: Annotation[], caption: string): string;
+/**
+ * The block without its question line, for a message that has no question.
+ *
+ * The line is an invitation for the reader's own words; with the box empty it is the last thing the bubble shows
+ * and the only thing a chip would be folded away from, so it goes.
+ */
+export declare function withoutEmptyQuestion(block: string): string;

package/lib/types/client.d.ts

@@ -12,9 +12,11 @@
  * compiled output in `window.__ModuleLoader__.load(...)`, which is the loader contract itself.
  */
 import { type Palette, type PaletteMode } from './render/palette.js';
+import { type DocumentLike } from './annotation.js';
 export interface ReactLike {
     createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
-    useState?: <T>(initial: T) => [T, (next: T) => void];
+    useState?: <T>(initial: T) => [T, (next: T | ((previous: T) => T)) => void];
+    useEffect?: (effect: () => void | (() => void), deps?: ReadonlyArray<unknown>) => void;
 }
 export interface SlotContext {
     slots: {
@@ -29,7 +31,6 @@ export interface PluginShape {
     /** The whiteboard mount, with its scheduler injectable. `apply` calls this with the default. */
     mount: (ctx: SlotContext, options?: MountOptions) => unknown;
 }
-/** A settled tool call, as the host hands it to a view. */
 export interface ToolCallProps {
     phase?: string;
     toolName?: string;
@@ -53,12 +54,93 @@ export declare const WHITEBOARD_ID = "model-everything-diagram";
 /** What the whiteboard opens with: a diagram the reader can edit rather than an empty box. */
 export declare const WHITEBOARD_SAMPLE: string;
 /**
- * The view for one tool name.
+ * The card for a drawing: the source the call carried, drawn by the renderer that wrote the file.
  *
- * The drawing is emitted as markup, so React receives it through `dangerouslySetInnerHTML`. That is safe
- * only because the writer escapes every value that came from a report or a model, which the render suite
- * pins with an injection case.
+ * Drawing it here rather than replaying the SVG means the card and the file are one picture from one
+ * engine, and it costs the result nothing. Lines the renderer refused are listed under the drawing: a
+ * card that hid them would show a picture that is missing something, which is the failure the tool
+ * exists to prevent.
  */
+/** A create-element function with this package's calling convention, so a shared builder fits both seats. */
+type H = (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+/** What an annotation editor shows, shared by the two surfaces that offer one. */
+export interface AnnotationState {
+    picked: {
+        id: string;
+    } | null;
+    note: string;
+    pending: Array<{
+        nodeId: string;
+        note: string;
+    }>;
+    status: string;
+    /** Whether the pending list is expanded under the count. */
+    open?: boolean;
+    /** Where the editor sits, in the drawing's own coordinates: beside the node the reader picked. */
+    anchor?: {
+        left: number;
+        top: number;
+    };
+    /** The correction the dock applied after measuring where the chip actually landed. */
+    dockFix?: {
+        dx: number;
+        dy: number;
+    };
+}
+export interface AnnotationActions {
+    onNote: (value: string) => void;
+    onAdd: () => void;
+    onAddAndSend: () => void;
+    onSend: () => void;
+    onClear: () => void;
+    onCancel: () => void;
+    onToggle: () => void;
+    onRemove: (index: number) => void;
+}
+/**
+ * The annotation surface: a floating editor over the drawing, and a count of what is waiting.
+ *
+ * Floating rather than inline, because the reader is looking at a picture and the editor must not move it.
+ * The notes stay in a list until one message is composed from them: the reader's input box is theirs, and N raw
+ * fragments in it would be exactly the mess this feature is meant to avoid. Colours come from the host's tokens,
+ * so light and dark themes need no separate code.
+ */
+export declare function annotationPanel(h: H, state: AnnotationState, actions: AnnotationActions, options?: {
+    floating?: boolean;
+    document?: DocumentLike;
+    dockFix?: {
+        dx: number;
+        dy: number;
+    };
+    dockChip?: boolean;
+}): unknown;
+/** Remember what would leave with the next message, and start watching for that message. */
+export declare function setPendingBlock(text: string): void;
+/**
+ * The dock, as a layer on `document.body`.
+ *
+ * A `position: fixed` node still positions against the nearest transformed ancestor, and the composer sits
+ * inside one - which is why every coordinate this plugin computed landed inside the box. The shipped
+ * annotation plugin sidesteps it the same way: its chip is a body-level layer, so fixed means the viewport.
+ * Size and place come from the composer card's own rectangle, measured after every layout change.
+ */
+interface DockHandlers {
+    onToggle: () => void;
+    onSend: () => void;
+    onRemove: (index: number) => void;
+}
+/** Keep the docked count in step with the pending list. Called from a render path, so it cannot throw. */
+export declare function updateDockLayer(items: Array<{
+    nodeId: string;
+    note: string;
+}>, open: boolean, handlers: DockHandlers): void;
+/**
+ * Tell this module when a message leaves, by watching the one signal the host gives: the draft empties.
+ *
+ * A note that was committed is in the draft, so after the send there is nothing left to keep - and a chip still
+ * counting a note that has already gone out is the plugin lying about its own state.
+ */
+export declare function onMessageSent(listener: () => void): () => void;
 export declare function viewFor(React: ReactLike, overrides?: Partial<Palette>): (props: ToolCallProps) => unknown;
 /**
  * The whiteboard: paste a diagram, get a drawing, zoom it.
@@ -81,3 +163,4 @@ export interface MountOptions {
  */
 export declare function mountWhiteboard(React: ReactLike, ctx: SlotContext, options?: MountOptions): unknown;
 export default function factory(require: (name: string) => unknown): PluginShape;
+export {};

package/lib/types/diagram.d.ts

@@ -31,4 +31,11 @@ export interface ComponentContext {
     };
 }
 export declare function apply(ctx: ComponentContext, config: Config): void;
+/**
+ * Offer an annotation as a session command, so a page can send one without a composer.
+ *
+ * Optional on purpose, and failure-tolerant on purpose: a host without the commands service keeps the
+ * composer path, and a registration that throws must not take the drawing tools down with it.
+ */
+export declare function registerAnnotateCommand(ctx: unknown): void;
 export declare const inject: string[];

package/lib/types/gate.d.ts

@@ -10,13 +10,15 @@
  *
  * Why it is a separate row. The plugin's doctrine is that a capability is discoverable
  * through its own tool description or skill text. Injection departs from that, so it is
- * opt-in and mounted as its own component: install it, disable it, or never enable it,
- * without touching the tools or the skills. `enabled` is a live switch, so the Web Plugins
- * page flips it inside a running host.
+ * mounted as its own component: the bundle's patch enables it, and the row can be turned off
+ * or removed without touching the tools or the skills. `enabled` is a live switch, so the Web
+ * Plugins page flips it inside a running host.
  *
- * Why it is off by default. It costs tokens in every session that turns it on, to fix a
- * problem text-only routing was measured not to have once the session engages. A deployment
- * that wants it says so; the default pays nothing.
+ * Why the bundle turns it on. Measured: a session that never decides to load a skill is never
+ * routed, and the catalog line is cut at 500 characters, so a domain the request names can be
+ * invisible at the moment of choosing. The cost is a fixed message in every session, which is
+ * why the switch is live and documented: turn it off where the bundle's default is wrong. The
+ * component's own `enabled` script default is off, so a bare `app.add(gate)` injects nothing.
  *
  * What it does not do. It routes; it checks nothing. It cannot make a skill load, and it
  * does not restate the doctrine - the skill bodies carry that, and duplicating them here

package/lib/types/render/paint.d.ts

@@ -44,6 +44,8 @@ export interface Point {
 }
 export interface BoxShape {
     kind: 'box';
+    /** Which node this box is. It travels into the markup, so a reader can target one node by delegation. */
+    id: string;
     x: number;
     y: number;
     width: number;

package/lib/types/transcript.d.ts

@@ -0,0 +1,82 @@
+/**
+ * What an annotation message looks like after it has been sent.
+ *
+ * The message is one block of plain lines: a fixed opening, numbered items, a question line, then the reader's
+ * own words. That is the right thing for the model and the wrong thing to read as a human - the reader wrote one
+ * note about one node, and what landed is a page of protocol.
+ *
+ * The host renders a user message as text inside elements it owns and re-renders. So this never assigns an
+ * element's text: that deletes its children, React reconciles from a tree that no longer matches, and whole
+ * turns come back mangled. It edits the text NODES instead - trim the run before the cut, remove the runs that
+ * held the block - and puts the chip in as a sibling, exactly the way the shipped annotation plugin does it.
+ *
+ * Everything here is defensive: a page without the elements, an element without text nodes, an element already
+ * handled. A decorator that throws would take a render pass with it.
+ */
+/** The first words of every annotation block, used to recognise one in the transcript. */
+export declare const TRANSCRIPT_MARKER = "Diagram annotations -";
+export interface TranscriptNode {
+    nodeType?: number;
+    nodeValue?: string | null;
+    textContent?: string | null;
+    style?: Record<string, string | undefined>;
+    setAttribute?: (name: string, value: string) => void;
+    getAttribute?: (name: string) => string | null;
+    addEventListener?: (type: string, handler: () => void) => void;
+    querySelectorAll?: (selector: string) => ArrayLike<TranscriptNode>;
+    getBoundingClientRect?: () => {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    closest?: (selector: string) => TranscriptNode | null;
+    childNodes?: ArrayLike<TranscriptNode>;
+    nextSibling?: TranscriptNode | null;
+    appendChild?: (node: TranscriptNode) => unknown;
+    removeChild?: (node: TranscriptNode) => unknown;
+    parentNode?: {
+        insertBefore?: (node: TranscriptNode, before: TranscriptNode | null) => unknown;
+        removeChild?: (node: TranscriptNode) => unknown;
+    } | null;
+}
+export interface TranscriptDocument {
+    querySelectorAll?: (selector: string) => ArrayLike<TranscriptNode>;
+    createElement?: (tag: string) => TranscriptNode;
+}
+/** One note as the block states it. */
+export interface AnnotationItem {
+    index: number;
+    node: string;
+    note: string;
+}
+/** The count in the opening line, for the chip; null when the line says something unexpected. */
+export declare function annotationCountOf(text: string): number | null;
+/** The reader's own words: what follows the question line, or nothing when the note was the whole message. */
+export declare function questionOf(text: string): string;
+/** The notes the block carries, read back out of its lines, so a reader sees what the model saw. */
+export declare function itemsOf(text: string): AnnotationItem[];
+/**
+ * Drop everything before the cut from the text nodes, and leave the reader's own words.
+ *
+ * The nodes are the only thing written: an element's `textContent` would take its child elements with it.
+ */
+export declare function cutTextNodes(nodes: TranscriptNode[], cut: number): boolean;
+/** Kept for the tests that assert the selector exists; the ancestor walk is deliberately not used. */
+export declare const FOREIGN_SELECTOR = "[data-annotation-for-dsh], [data-annotation-overlay], [data-annotation-chip], [data-annotation-tip-layer]";
+/**
+ * Fold every annotation message in the transcript behind its count, and answer how many were folded.
+ *
+ * Idempotent: an element that already carries the marker is skipped, so the observer can call this on every
+ * change without stacking chips. Only the element whose text is the message is touched, and only its text nodes.
+ */
+export declare function decorateTranscript(doc: TranscriptDocument | undefined, label?: string, title?: string): number;
+/**
+ * One pass, and nothing that keeps running.
+ *
+ * There is deliberately no observer and no timer here. Both were tried: an observer over the document plus a
+ * one-second interval turns every DOM change into a full selector scan, and a streaming conversation changes the
+ * DOM many times a second - the container stopped responding. A caller that wants the fold has to decide when
+ * to run it, on a container it chose.
+ */
+export declare function startTranscriptDecoration(doc: TranscriptDocument | undefined, label?: string, title?: string): () => void;