yarramate 1.2.0 → 1.4.0

package/dist/visual-app-lib/types/relationship-drafting.d.ts

@@ -33,8 +33,16 @@ export declare const connectableKinds: (graph: CanvasGraph, fromId: string, toId
  * relationship kind is a single lowercase word. A collision takes a numeric
  * suffix rather than a hash, because the id is authored text a human will read
  * in a diff.
+ *
+ * `reserved` carries ids the graph does not know yet: a staged-but-uncommitted
+ * draft never enters the rendered graph, so without it a second relationship
+ * between the same pair re-proposed the identical id and the editor's
+ * replace-by-target staging silently swallowed the first (#306). The schema
+ * places no uniqueness on the (from, kind, to) triple - parallel relationships
+ * with distinct ids compile cleanly - so the id proposal is the only place the
+ * collision can be stepped past.
  */
-export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string) => string;
+export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string, reserved?: Iterable<string>) => string;
 /**
  * The operation that lands a drafted relationship, or `null` when the draft is
  * one the table does not permit.
@@ -47,5 +55,16 @@ export declare const proposeRelationshipId: (graph: CanvasGraph, fromId: string,
  * relationship has to live somewhere, both endpoints are equally defensible,
  * and the source is where a reader looking for what this thing does would go
  * first.
+ *
+ * A caller holding drafts the graph has not landed yet - an editor with a
+ * pending changeset - passes their ids as `reserved`, so a second parallel
+ * relationship steps to `-2` instead of colliding with the first (#306).
+ */
+export declare const draftRelationship: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string, reserved?: Iterable<string>) => YarramateOperation | null;
+/**
+ * The ids a pending changeset already claims, for `proposeRelationshipId`'s
+ * `reserved` parameter. Every operation that names a subject id reserves it -
+ * an update's id is already in the graph and reserving it twice is harmless,
+ * while an add's id is exactly the one the graph cannot know yet.
  */
-export declare const draftRelationship: (graph: CanvasGraph, fromId: string, kind: RelationshipKind, toId: string) => YarramateOperation | null;
+export declare const stagedSubjectIds: (operations: readonly YarramateOperation[]) => readonly string[];

package/dist/visual-app-lib/types/subject-identity.d.ts

@@ -0,0 +1,34 @@
+export declare const normalizeLabel: (label: string) => readonly string[];
+export declare const headTokens: (tokens: readonly string[]) => readonly string[];
+export declare const similarity: (left: string, right: string) => number;
+export interface IdentitySubject {
+    readonly id: string;
+    readonly kind: string;
+    readonly labels: readonly string[];
+    readonly owner?: string;
+    readonly neighbours: ReadonlySet<string>;
+    readonly distinctFrom: ReadonlySet<string>;
+}
+export interface NearDuplicatePair {
+    readonly left: string;
+    readonly right: string;
+    readonly score: number;
+    readonly corroboration: 'lexical' | 'owner' | 'neighbourhood';
+}
+export declare const strongLexicalThreshold = 0.95;
+export declare const moderateLexicalThreshold = 0.8;
+export declare const lexicalScore: (left: IdentitySubject, right: IdentitySubject) => number;
+/**
+ * Every candidate near-duplicate pair, sorted by subject id. Only subjects
+ * of the same qualified kind are compared: kind is the cheapest structural
+ * disagreement there is, and it also bounds the pairwise cost to the square
+ * of the largest kind bucket rather than of the whole model.
+ */
+export declare const findNearDuplicates: (subjects: readonly IdentitySubject[]) => readonly NearDuplicatePair[];
+/**
+ * Both members of every candidate pair, mapped to their counterparts. The
+ * question attaches to both sides deliberately: `ask --advise` filters open
+ * questions to the subjects in a slice, so a finding recorded only against
+ * the lexically-first member would vanish from a slice seeded on the other.
+ */
+export declare const nearDuplicateIndex: (subjects: readonly IdentitySubject[]) => ReadonlyMap<string, readonly string[]>;

package/dist/visual-app-lib/types/visual-app/App.d.ts

@@ -1,5 +1,6 @@
+import { type DecorationMap } from "./graph-canvas.js";
 import type { EditorHost } from "./editor-host.js";
-import { type RightSectionId } from "./workspace-state.js";
+import { type EditorPointer, type RightSectionId } from "./workspace-state.js";
 /**
  * The editor.
  *
@@ -8,8 +9,32 @@ import { type RightSectionId } from "./workspace-state.js";
  * embedder's own store with no server at all. `sections` is what the host
  * wants shown - a product with no agent behind it leaves `chat` out, and the
  * section and the session button go with it.
+ *
+ * `readOnly` is one flag, threaded once (#298, ADR 0117): a viewer keeps
+ * everything that reads - the canvas, the tree, the query fields, the facts,
+ * the questions - and every affordance that stages or commits is absent
+ * rather than disabled. A UI posture only: whatever this shell draws, the
+ * host still answers for its own store.
  */
-export declare const App: ({ host, sections, }: {
+export declare const App: ({ host, sections, readOnly, decorations: initialDecorations, onReady, }: {
     readonly host: EditorHost;
     readonly sections?: readonly RightSectionId[];
+    readonly readOnly?: boolean;
+    /**
+     * The host's per-subject marks at mount time (#314, ADR 0119) - the
+     * initial value only, the way React means an initial value: later
+     * hand-overs travel through the pointer's `setDecorations`, each one
+     * replacing the map wholesale. Client state like selection, so it rides a
+     * prop rather than the `EditorHost` seam.
+     */
+    readonly decorations?: DecorationMap;
+    /**
+     * How the mount layer's handle reaches this shell's reducer (#297,
+     * ADR 0118). Called once, after the first render, with the pointer the
+     * handle delegates to - which is what makes the handle's pre-ready
+     * false-return window real. Selection and dialog state are client state,
+     * so this rides a prop rather than the `EditorHost` seam: the protocol
+     * carries documents, not gestures.
+     */
+    readonly onReady?: (pointer: EditorPointer) => void;
 }) => import("react").JSX.Element;

package/dist/visual-app-lib/types/visual-app/badges.d.ts

@@ -4,4 +4,5 @@ export declare const LIFECYCLE_BADGE_URI: Record<LifecycleStatus, string>;
 export declare const EVIDENCE_BADGE_URI: string;
 export declare function ownerColorOf(owner: string | null): string | null;
 export declare function ownerBadgeUri(owner: string, initials: string): string;
+export declare function openQuestionsBadgeUri(count: number): string;
 export declare function ownerInitialsOf(owner: string | null): string | null;

package/dist/visual-app-lib/types/visual-app/connection-panel.d.ts

@@ -15,9 +15,17 @@ import type { ConnectionDraft } from './workspace-state.js';
  * means an endpoint outside the ArchiMate vocabulary rather than a dead end,
  * and the panel says which.
  */
-export declare const ConnectionPanel: ({ draft, graph, onStage, onCancel, }: {
+export declare const ConnectionPanel: ({ draft, graph, reservedIds, onStage, onCancel, }: {
     readonly draft: ConnectionDraft;
     readonly graph: CanvasGraph;
+    /**
+     * Ids the pending changeset already claims. The graph only knows what has
+     * landed, so without these a second relationship between the same pair
+     * proposed the identical id and replace-by-target staging swallowed it
+     * silently (#306). Required rather than defaulted: a caller has to say
+     * what is staged, even when the answer is nothing.
+     */
+    readonly reservedIds: readonly string[];
     readonly onStage: (operation: YarramateOperation) => void;
     readonly onCancel: () => void;
 }) => React.ReactElement;

package/dist/visual-app-lib/types/visual-app/context-menu-model.d.ts

@@ -24,6 +24,7 @@
  */
 import type { CanvasGraph } from "../graph-projection.js";
 import type { VisualKindOption } from "../adapters/visual/protocol-contract.js";
+import type { ActiveViewMembership } from "./state.js";
 /** The id of the "All subjects" row, which is the absence of a view. */
 export declare const ALL_SUBJECTS_VIEW = "";
 export type ContextMenuTarget = {
@@ -144,14 +145,22 @@ export interface ContextMenuContext {
     /** Whether anything at all is narrowing the canvas right now. */
     readonly filtered: boolean;
     /**
-     * The active view's own membership list, or `null`.
+     * How the active view can be told what it holds, or `null` when no view is
+     * active and there is nothing to tell.
      *
-     * `null` covers both "no view is active" and "the active view describes its
-     * subjects with facets": in neither case is there a list to put a subject
-     * into or take it out of, so neither offers a membership item at all rather
-     * than offering one that would do nothing (#255).
+     * A view that enumerates its subjects is told by its list; one that
+     * describes them with facets is told by `exclude` (#267, ADR 0122). A
+     * faceted view used to be `null` here, on the reasoning that an item which
+     * could only ever do nothing is worse than no item (#255) - true of adding a
+     * subject to a rule, and never true of taking one out of it.
      */
-    readonly membership: readonly string[] | null;
+    readonly membership: ActiveViewMembership | null;
+    /**
+     * A viewer, not an author (#298, ADR 0117). A read-only menu keeps the items
+     * that read or navigate and drops every item whose intent stages a change -
+     * absent, never disabled.
+     */
+    readonly readOnly?: boolean;
 }
 /**
  * The menu for a target, already ordered: view groups first, model groups

package/dist/visual-app-lib/types/visual-app/graph-canvas.d.ts

@@ -1,22 +1,65 @@
 import type React from 'react';
 import cytoscape from 'cytoscape';
-import type { Core, NodeCollection } from 'cytoscape';
-import type { CanvasGraph, CanvasEdge } from '../graph-projection.js';
+import type { Core, ElementDefinition, NodeCollection } from 'cytoscape';
+import type { CanvasGraph, CanvasNode, CanvasEdge } from '../graph-projection.js';
 import { type NestingKind } from '../nesting.js';
+import { type LayoutDirection } from '../layout-direction.js';
 import type { VisualLayoutPositions, VisualLayoutSavePayload } from '../adapters/visual/protocol-contract.js';
 import { LAYER_COLORS } from '../notation/archimate.js';
 export { LAYER_COLORS };
-export declare function buildLayoutConfig(): cytoscape.LayoutOptions;
-export declare function buildStylesheet(showLifecycle: boolean, showEvidence: boolean, showOwnership: boolean): cytoscape.StylesheetJsonBlock[];
+export declare function steppedZoom(current: number, direction: 1 | -1): number;
+export declare function buildLayoutConfig(direction: LayoutDirection): cytoscape.LayoutOptions;
+/**
+ * The closed mark vocabulary a host may hand the mounted viewer (#314,
+ * ADR 0119). Three marks, because three is what comparison against another
+ * model needs and a fourth waits for the demand that names it. What a mark
+ * MEANS - added relative to what, changed since when - lives entirely on the
+ * host's side of the seam: this canvas renders marks, it never diffs.
+ */
+export type DecorationMark = 'added' | 'removed' | 'changed';
+/**
+ * Subject id (concepts and relationships alike) to mark. The whole map is the
+ * unit of exchange: each hand-over REPLACES the previous marks wholesale,
+ * never merges into them, and an id the current model does not name marks
+ * nothing, silently - the host may be describing subjects this model has not
+ * gained (or has already lost).
+ */
+export type DecorationMap = Readonly<Record<string, DecorationMark>>;
+/**
+ * Marks every subject the host's decoration map names, the exact class
+ * mechanism faults use: previous `deco-*` classes come off every element
+ * first (replacement is wholesale, the map is the unit), then each id that
+ * names a drawn node or edge gains its mark's class. Unknown ids are
+ * silently inert. The `faulted` class is never touched here, and the
+ * stylesheet orders the fault rule after the decoration rules, so a subject
+ * both decorated and refused reads as refused.
+ */
+export declare function applyDecorations(cy: Core, decorations: DecorationMap): void;
+export declare function buildStylesheet(showLifecycle: boolean, showEvidence: boolean, showOwnership: boolean, showNudges: boolean): cytoscape.StylesheetJsonBlock[];
 export declare function resolveNestingParents(edges: readonly CanvasEdge[], nesting: readonly NestingKind[], kindOf: (id: string) => string): {
     readonly parentOf: ReadonlyMap<string, string>;
     readonly consumedEdgeIds: ReadonlySet<string>;
 };
+export declare function graphToElements(graph: CanvasGraph, nesting: readonly NestingKind[], openQuestionCounts: ReadonlyMap<string, number>): ElementDefinition[];
+export declare function filteredSubjectCount(nodes: readonly Pick<CanvasNode, 'id' | 'name' | 'kindLabel'>[], matchedIds: readonly string[] | null, quickFilterText: string): number;
 export declare function applyFilter(cy: Core, matchedIds: readonly string[] | null, quickFilterText: string): void;
-export declare function relayoutVisible(cy: Core): void;
+export declare function relayoutVisible(cy: Core, direction: LayoutDirection): void;
+export declare function fitVisible(cy: Core): boolean;
 export declare const DRAG_SAVE_DEBOUNCE_MS = 500;
 export declare function buildPositionMap(nodes: NodeCollection): VisualLayoutPositions;
 export declare function applySavedPositions(cy: Core, saved: VisualLayoutPositions | undefined): void;
+export declare function effectiveSavedPositions(saved: VisualLayoutPositions | undefined, viewId: string, discardedViews: ReadonlySet<string>): VisualLayoutPositions | undefined;
+export declare function savedLayoutInForce(saved: VisualLayoutPositions | undefined, graphNodeIds: readonly string[], matchedIds: readonly string[] | null): boolean;
+export declare function modelPositionOf(rendered: {
+    readonly x: number;
+    readonly y: number;
+}, pan: {
+    readonly x: number;
+    readonly y: number;
+}, zoom: number): {
+    readonly x: number;
+    readonly y: number;
+};
 export interface DragSaveHandle {
     /** Cancels a queued save without unbinding the drag listener. */
     readonly cancelPending: () => void;
@@ -46,13 +89,41 @@ interface GraphCanvasProps {
     readonly nesting: readonly NestingKind[];
     /** Subjects a diagnostic named, marked so a failure is visible where it is. */
     readonly faultedIds: ReadonlySet<string>;
+    /**
+     * The host's per-subject marks (#314, ADR 0119), rendered as `deco-*`
+     * classes the way faults are rendered. The map replaces wholesale on every
+     * change; an empty map draws nothing, an unknown id marks nothing, and a
+     * subject that is also faulted reads as faulted.
+     */
+    readonly decorations: DecorationMap;
     readonly showLifecycle: boolean;
     readonly showEvidence: boolean;
     readonly showOwnership: boolean;
+    readonly showNudges: boolean;
+    /** Open-question count per subject id, from the model's interrogation
+     * overlay; an empty map (host shipped no overlay) draws no chips. */
+    readonly openQuestionCounts: ReadonlyMap<string, number>;
     readonly activeViewId: string;
+    /**
+     * Which way the active view runs its layers (#274, ADR 0121), from its
+     * `presentation.direction`. A view that declares none is handed
+     * `DEFAULT_DIRECTION`, so the canvas never has to decide what silence means.
+     */
+    readonly direction: LayoutDirection;
     /** Saved layout for the active view, or undefined when it has none yet. */
     readonly savedPositions: VisualLayoutPositions | undefined;
     readonly onSaveLayout: (payload: VisualLayoutSavePayload) => void;
+    /**
+     * A kind dropped from the palette (#295): the kind's label and the model
+     * position under the pointer. Optional because only a shell with a palette
+     * has anything to drop; a host without one never sees a drop at all - the
+     * `dragover` acceptance is gated on the callback too, so a stray drag is
+     * left to the browser's default refusal.
+     */
+    readonly onKindDrop?: (kindLabel: string, position: {
+        readonly x: number;
+        readonly y: number;
+    }) => void;
     /**
      * A way to take a picture of what is drawn, handed up once the instance
      * exists and withdrawn when it goes. The shell holds it so a menu item can
@@ -70,4 +141,4 @@ interface GraphCanvasProps {
  * - Wires node/edge tap handlers to call onSelect(id, type)
  * - Reflects selectedId prop as a visual highlight class on the matching element
  */
-export declare function GraphCanvas({ graph, selectedId, onSelect, onContextMenu, matchedIds, quickFilterText, nesting, faultedIds, activeViewId, savedPositions, onSaveLayout, onCanvasReady, showLifecycle, showEvidence, showOwnership, }: GraphCanvasProps): React.ReactElement;
+export declare function GraphCanvas({ graph, selectedId, onSelect, onContextMenu, matchedIds, quickFilterText, nesting, faultedIds, decorations, activeViewId, direction, savedPositions, onSaveLayout, onKindDrop, onCanvasReady, showLifecycle, showEvidence, showOwnership, showNudges, openQuestionCounts, }: GraphCanvasProps): React.ReactElement;

package/dist/visual-app-lib/types/visual-app/kind-palette.d.ts

@@ -0,0 +1,37 @@
+import type React from 'react';
+import type { VisualKindOption } from '../adapters/visual/protocol-contract.js';
+/**
+ * The kind palette (#295): the profile's concept kinds, listed to be picked up.
+ *
+ * The kinds are the same vocabulary the Add-subject dialog's Kind select
+ * compiles from - `vocabulary.conceptKinds`, sent with every model frame - so
+ * nothing here decides what a workspace may contain. A row is a thing to drag
+ * onto the canvas, and a thing to click for the same result without a pointer
+ * gesture: either way the details dialog opens with the kind already chosen,
+ * and the palette itself holds nothing afterwards (ADR 0116).
+ */
+/**
+ * The drag payload's type. Custom rather than `text/plain`, so the canvas
+ * accepts exactly what the palette offers and a stray text drop onto the
+ * diagram stays inert. The payload is the kind's LABEL, not its full identity:
+ * a document names a kind the short way, and `apply` refuses the identity as
+ * an unknown kind (`YM401`) - the same rule the dialog's own select follows.
+ */
+export declare const KIND_MIME = "application/x-yarramate-kind";
+export interface PaletteGroup {
+    readonly layer: string;
+    readonly kinds: readonly VisualKindOption[];
+}
+/**
+ * Rows grouped by layer, in the profile's own layer order - the same bands the
+ * model tree groups subjects by, so the palette and the rail read as one
+ * organisation. Within a group the wire's order is kept: the vocabulary
+ * arrives sorted and re-sorting it here would be a second opinion.
+ */
+export declare const paletteGroups: (kinds: readonly VisualKindOption[]) => readonly PaletteGroup[];
+export declare const KindPalette: ({ kinds, onPick, }: {
+    readonly kinds: readonly VisualKindOption[];
+    /** A kind chosen without the drag - a click, a keyboard - which opens the
+     * same dialog a drop does. */
+    readonly onPick: (kindLabel: string) => void;
+}) => React.ReactElement;

package/dist/visual-app-lib/types/visual-app/local-host.d.ts

@@ -34,5 +34,47 @@ export interface LocalHostOptions {
     readonly description?: string;
     /** Told after every landed commit, so a host can persist what it was given. */
     readonly onCommit?: (documents: readonly string[]) => void;
+    /**
+     * The question catalogue the questions section evaluates, or the shipped
+     * `core-enrichment` one when absent (#328).
+     *
+     * The engine is yarramate's and so is the UI; the QUESTIONS belong to
+     * whoever adopted it. `core-enrichment` is a general modelling interview,
+     * right for this repository's own CLI and for a host with no domain of its
+     * own, and wrong for a product whose interview is about its own subject
+     * matter. Until this existed a host could have the questions UI only by
+     * also running yarramate's catalogue, so a product with its own interview
+     * had to omit the section and show its questions on a separate surface,
+     * away from the model they are about.
+     *
+     * Bytes rather than a parsed catalogue, matching what the seam beneath
+     * already takes: a catalogue that does not load leaves the overlay absent
+     * rather than failing the mount, because the overlay is a garnish on the
+     * model and a model frame must not be blocked by it.
+     */
+    readonly catalogue?: {
+        readonly path: string;
+        readonly source: string;
+    };
+    /**
+     * Questions this host has already dealt with and does not want asked again
+     * (#328).
+     *
+     * A host-supplied catalogue alone does not close this: the editor evaluates
+     * the catalogue itself and cannot know that a reviewer set a question aside,
+     * with a reason, recorded somewhere the editor cannot see. Without this the
+     * pane would go on asking a question its own product had answered.
+     *
+     * `subject` absent dismisses the question wherever it appears - the
+     * workspace-scoped entry and every subject's - which is "stop asking this".
+     * `subject` present dismisses it for that subject alone, which is "not for
+     * this one". Dismissal hides a question from the pane and changes nothing
+     * about the model or about what `ask --open` reports; the interview is not
+     * the editor's to settle.
+     */
+    readonly dismissed?: readonly {
+        readonly questionId: string;
+        readonly subject?: string;
+    }[];
 }
 export declare const createLocalHost: (options: LocalHostOptions) => EditorHost;

package/dist/visual-app-lib/types/visual-app/mount.d.ts

@@ -1,4 +1,5 @@
 import { type LocalHostOptions } from './local-host.js';
+import type { DecorationMap } from './graph-canvas.js';
 import type { EditorHost } from './editor-host.js';
 import { type RightSectionId } from './workspace-state.js';
 import './styles.css';
@@ -19,6 +20,8 @@ import './styles.css';
  *   workspace,                          // a resolved manifest
  *   sections: ['properties', 'changes'],
  * })
+ * editor.select('app.checkout')       // as a canvas tap would (#297)
+ * editor.openDraft({ kind: 'goal' })  // as a palette pick would
  * // later
  * editor.unmount()
  * ```
@@ -26,6 +29,9 @@ import './styles.css';
  * `sections` is what the host wants shown. Chat is the one a product usually
  * leaves out: with no agent behind it there is nobody to talk to and nothing to
  * hand control back to, so the section and the session button go together.
+ *
+ * `readOnly: true` mounts a viewer (#298): the same canvas, tree, questions
+ * and properties, with every staging and committing affordance absent.
  */
 export interface MountOptions extends LocalHostOptions {
     /**
@@ -35,10 +41,72 @@ export interface MountOptions extends LocalHostOptions {
      * name the two it wants.
      */
     readonly sections?: readonly RightSectionId[];
+    /**
+     * A viewer, not an author (#298, ADR 0117). Every affordance that stages or
+     * commits a change is absent - not disabled - so a frozen snapshot renders
+     * with the authoring surface's visual language and none of its pen. A UI
+     * posture only: a host whose store also refuses writes has two independent
+     * defenses, and this option is not the one that guards the data.
+     */
+    readonly readOnly?: boolean;
+    /**
+     * The host's per-subject marks at mount time (#314, ADR 0119): subject id -
+     * concept or relationship - to `'added' | 'removed' | 'changed'`, rendered
+     * as class-based visual treatments the way faults are. This is the seam
+     * that lets a host with its own comparison model use the one viewer for
+     * decorated comparison: the SEMANTICS stay host-side - the viewer never
+     * diffs, it renders the marks it is handed. An id the model does not name
+     * is silently inert. This option is the initial map; a live comparison
+     * replaces it wholesale through the handle's `setDecorations`.
+     */
+    readonly decorations?: DecorationMap;
 }
+/**
+ * The handle a mount returns (#297, ADR 0118): the disposal it always had,
+ * and three ways for the host to point at the canvas. Each method is the
+ * programmatic twin of a gesture the surface already has - never a second
+ * write path: nothing here commits, and anything the opened affordances stage
+ * still goes through the changeset like every reviewer gesture.
+ *
+ * Every method answers with whether it acted. False means nothing moved: the
+ * id named nothing in the current model, the model has not arrived yet - the
+ * editor renders before its host's first frame lands - or the mount is a
+ * viewer (`readOnly`, #298) and the gesture would have reached for the pen.
+ */
 export interface MountedEditor {
     /** Releases the host and takes the editor out of the element. */
     readonly unmount: () => void;
+    /**
+     * Selects the subject - concept or relationship - on the canvas and in the
+     * inspector, exactly as a tap on it would, which also scopes the Open
+     * questions section to it.
+     */
+    readonly select: (subjectId: string) => boolean;
+    /**
+     * Opens the Add-subject dialog, with the kind preselected when one is
+     * given - the same seed a palette pick rides (#295). Without a kind, the
+     * plain no-default form.
+     */
+    readonly openDraft: (options?: {
+        readonly kind?: string;
+    }) => boolean;
+    /**
+     * Arms the connection tool from the named subject, exactly as the
+     * inspector's Connect does: the next selection becomes the target and the
+     * kinds on offer are derived from the two endpoints.
+     */
+    readonly startConnection: (fromSubjectId: string) => boolean;
+    /**
+     * Replaces the per-subject marks wholesale (#314, ADR 0119) - never a
+     * merge: the map handed here is the map drawn, and `{}` clears every mark.
+     * The one handle method that is not a gesture's twin, because no gesture
+     * decorates: it is the live half of the `decorations` mount option, for a
+     * comparison that moves under an open viewer. Decorating is reading, so it
+     * works under `readOnly`, and unknown ids are silently inert - false is
+     * only the shared not-there window: before the shell's first render, or
+     * after unmount.
+     */
+    readonly setDecorations: (decorations: DecorationMap) => boolean;
 }
 export declare const mountEditor: (element: Element, options: MountOptions) => MountedEditor;
 /**
@@ -47,10 +115,13 @@ export declare const mountEditor: (element: Element, options: MountOptions) => M
  * Exported for the case `mountEditor` does not cover: a product that already
  * speaks the visual protocol - to its own server, over its own transport - and
  * wants the editor in front of it. The protocol is the contract (ADR 0081), so
- * anything that answers it is a host.
+ * anything that answers it is a host. `readOnly` composes: a custom host gets
+ * the same viewer posture `mountEditor` offers, and stays free to refuse
+ * writes on its own side of the seam as well.
  */
-export declare const mountEditorWith: (element: Element, host: EditorHost, sections?: readonly RightSectionId[]) => MountedEditor;
+export declare const mountEditorWith: (element: Element, host: EditorHost, sections?: readonly RightSectionId[], readOnly?: boolean, decorations?: DecorationMap) => MountedEditor;
 export type { EditorHost, EditorHostEvents } from './editor-host.js';
+export type { DecorationMap, DecorationMark } from './graph-canvas.js';
 export type { LocalHostOptions } from './local-host.js';
 export { createLocalHost } from './local-host.js';
 export { RIGHT_SECTIONS, type RightSectionId } from './workspace-state.js';

package/dist/visual-app-lib/types/visual-app/open-questions.d.ts

@@ -0,0 +1,15 @@
+import type { VisualInterrogationOverlay } from '../adapters/visual/wire.js';
+/**
+ * The interview, where the drawing happens (#292).
+ *
+ * One home for both scopes: a selected element shows the questions that name
+ * it — the `design --subject` reading of the model — and no selection shows
+ * the workspace-scoped questions, which name no subject and would otherwise
+ * be the model's biggest holes rendered nowhere. Read-only by design: the
+ * answer path stays `apply` (through the editor's own forms or an agent),
+ * never a text box here that would bypass the compile gate.
+ */
+export declare function OpenQuestions({ overlay, selectedId, }: {
+    readonly overlay: VisualInterrogationOverlay;
+    readonly selectedId: string | null;
+}): import("react").JSX.Element;

package/dist/visual-app-lib/types/visual-app/query-fields.d.ts

@@ -39,7 +39,7 @@ export declare const queryToFields: (query: ProjectionQuery | null) => QueryFiel
  * single-choice field is never sent, since `minItems: 1` on the schema's
  * array properties makes `[]` itself invalid. */
 export declare const composeQuery: (fields: QueryFields) => ProjectionQuery;
-export type PresentationFlag = 'showLifecycle' | 'showEvidence' | 'showOwnership';
+export type PresentationFlag = 'showLifecycle' | 'showEvidence' | 'showOwnership' | 'showNudges';
 /** The checkbox's onChange handler, extracted so it is directly testable in
  * isolation from rendering: it calls `onTogglePresentation` and nothing
  * else — never `composeQuery`/`scheduleApply`. These three flags are
@@ -61,9 +61,10 @@ export declare function QueryFacets({ fields, onChange, }: {
  * view document's `presentation` and never composed into a `ProjectionQuery`,
  * which is why they take their own handler rather than sharing `onChange`.
  */
-export declare function PresentationToggles({ showLifecycle, showEvidence, showOwnership, onTogglePresentation, }: {
+export declare function PresentationToggles({ showLifecycle, showEvidence, showOwnership, showNudges, onTogglePresentation, }: {
     readonly showLifecycle: boolean;
     readonly showEvidence: boolean;
     readonly showOwnership: boolean;
+    readonly showNudges: boolean;
     readonly onTogglePresentation: (flag: PresentationFlag, value: boolean) => void;
 }): import("react").JSX.Element;

package/dist/visual-app-lib/types/visual-app/query-panel.d.ts

@@ -131,6 +131,7 @@ export interface QueryPanelProps {
     readonly showLifecycle: boolean;
     readonly showEvidence: boolean;
     readonly showOwnership: boolean;
+    readonly showNudges: boolean;
     readonly onTogglePresentation: (flag: PresentationFlag, value: boolean) => void;
     readonly onToggleOpen: () => void;
     readonly onSelectTab: (tab: BottomPanelTabId) => void;
@@ -138,5 +139,11 @@ export interface QueryPanelProps {
      * write: what is on screen is what the reviewer is composing. */
     readonly onApply: (query: ProjectionQuery) => void;
     readonly onStage: (operation: VisualViewOperation) => void;
+    /**
+     * A viewer, not an author (#298): the fields still narrow the canvas - a
+     * live filter writes nothing - but the affordance that stages the edit as a
+     * view change is absent. The document still shows, because it is a fact.
+     */
+    readonly readOnly?: boolean;
 }
-export declare function QueryPanel({ nodes, activeFilter, view, open, tab, showLifecycle, showEvidence, showOwnership, onTogglePresentation, onToggleOpen, onSelectTab, onApply, onStage, }: QueryPanelProps): import("react").JSX.Element;
+export declare function QueryPanel({ nodes, activeFilter, view, open, tab, showLifecycle, showEvidence, showOwnership, showNudges, onTogglePresentation, onToggleOpen, onSelectTab, onApply, onStage, readOnly, }: QueryPanelProps): import("react").JSX.Element;

package/dist/visual-app-lib/types/visual-app/save-view.d.ts

@@ -1,3 +1,4 @@
+import type { LayoutDirection } from "../layout-direction.js";
 import type { ProjectionQuery } from "../projection.js";
 import type { VisualViewOperation, VisualViewSummary } from "../adapters/visual/protocol-contract.js";
 export interface SaveViewDialogProps {
@@ -52,12 +53,12 @@ export interface BuildPayloadParams {
     readonly showOwnership: boolean;
     /**
      * Whatever the view being overwritten already declared, carried through
-     * rather than restated. The canvas has no direction control - it draws
-     * ArchiMate, which is top-down by construction - but the LikeC4 export reads
-     * `presentation.direction`, so a save that simply omitted it would quietly
-     * drop a value the reviewer never saw and cannot have meant to discard.
+     * rather than restated. The canvas draws the direction now (#274, ADR 0121)
+     * and the LikeC4 export has always read it, but there is still no control
+     * that sets one: the view declares it, so a save that simply omitted it
+     * would drop a value the reviewer never asked to discard.
      */
-    readonly carriedDirection: "top-down" | "left-right" | undefined;
+    readonly carriedDirection: LayoutDirection | undefined;
 }
 /**
  * Pure translation from the form's local state to the staged operation — no
@@ -82,5 +83,10 @@ export declare const buildPayload: ({ id, taken, path, folder, title, descriptio
  * an overwrite was immediate and unundoable; a staged overwrite is a row the
  * reviewer can read, discard and undo before it lands, which is a better
  * answer than a dialog.
+ *
+ * Opened with a folder preset — "New folder…", "New view in this folder…" —
+ * the overwrite is disabled (#299): it carries the active view's own folder
+ * by design, so it is the one button that would silently drop the folder the
+ * reviewer just named.
  */
 export declare function SaveViewDialog({ views, activeViewId, query, layout, showLifecycle, showEvidence, showOwnership, open, folder, onClose, onStage, }: SaveViewDialogProps): import("react").JSX.Element | null;

package/dist/visual-app-lib/types/visual-app/shipped-catalogue.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The shipped question catalogue, bundled into the browser build so the
+ * embedded editor computes the same interrogation overlay the session
+ * server does (#292). The path is a diagnostic label, not a file: nothing
+ * in the browser resolves it.
+ */
+export declare const SHIPPED_CATALOGUE: {
+    readonly path: 'core-enrichment.yaml';
+    readonly source: string;
+};

package/dist/visual-app-lib/types/visual-app/state.d.ts

@@ -301,17 +301,28 @@ export declare const visualBrowserInputFor: (intent: VisualAppIntent, state: Vis
  * reporting itself as the reviewer's own.
  */
 /**
- * The active view's membership list, as the menus must read it.
+ * How the active view can be told what it holds, as the menus must read it.
  *
- * `null` where there is no list to edit: no view is active, or the view
- * describes its subjects with facets rather than naming them.
+ * `null` only where there is no view at all. A view that ENUMERATES its
+ * subjects is told by editing that list; a view that describes them with
+ * FACETS is told by editing `exclude`, the exception a rule cannot state
+ * (#267, ADR 0122). Both are membership; they differ in which field moves and
+ * in which direction, which is why the shape is a union rather than a list
+ * with a flag.
  *
  * Read through the PENDING row when one is staged, not off the saved document.
  * A reviewer who has just added a subject and right-clicks it again must be
  * offered "Remove from view"; a menu built from the saved list would offer
  * "Add to this view" a second time and stage nothing.
  */
-export declare const activeViewMembership: (state: VisualAppState) => readonly string[] | null;
+export type ActiveViewMembership = {
+    readonly kind: "enumerated";
+    readonly subjects: readonly string[];
+} | {
+    readonly kind: "faceted";
+    readonly excluded: readonly string[];
+};
+export declare const activeViewMembership: (state: VisualAppState) => ActiveViewMembership | null;
 export declare const filterToReresolve: (frame: VisualServerFrame, state: VisualAppState) => {
     readonly query: ProjectionQuery;
     readonly source: FilterSource;