yarramate 1.2.0 → 1.3.0

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

@@ -2,7 +2,8 @@
  * What the left rail shows, as data.
  *
  * The rail is two trees over things the session already has — the saved views
- * and the subjects the model declares — so everything it decides is a pure
+ * with the reviewer's staged view operations merged over them (ADR 0114), and
+ * the subjects the model declares — so everything it decides is a pure
  * function of those plus what the reviewer typed. It lives outside the
  * component for the reason `filterToReresolve` does: this repo renders React
  * with `renderToStaticMarkup` and has no DOM test environment, so logic that
@@ -13,7 +14,8 @@
  */
 import type { CanvasNode } from "../graph-projection.js";
 import type { Layer } from "../profile.js";
-import type { VisualViewSummary } from "../adapters/visual/protocol-contract.js";
+import type { VisualViewOperation, VisualViewSummary } from "../adapters/visual/protocol-contract.js";
+import { type FilterableSubject } from "./subject-filter.js";
 export declare const VIEWS_ROOT_KEY = "views";
 export declare const MODEL_ROOT_KEY = "model";
 /** Collapse keys are strings so one set holds every branch of both trees. */
@@ -24,12 +26,30 @@ export declare const layerKey: (layer: string) => string;
 export declare const modelFolderKey: (folder: string) => string;
 /** Where a subject with no resolved layer is grouped, last. */
 export declare const UNLAYERED = "unlayered";
+/**
+ * How a row relates to the pending changeset (ADR 0114). `"new"` is a staged
+ * `write-view` at a path nothing has landed; `"overwrite"` is one at a path a
+ * landed view occupies; `"delete"` is a staged `delete-view`. A landed row
+ * nothing pending touches carries `null`.
+ */
+export type ViewRowStaging = "new" | "overwrite" | "delete";
 export interface ViewTreeRow {
     readonly id: string;
     readonly title: string;
     readonly path: string;
-    readonly subjectCount: number;
+    /**
+     * `null` when nothing has measured it: a staged NEW view has no landed
+     * document, and resolving its query needs the semantic graph the browser
+     * does not hold — and, while the tree filter narrows, every landed view
+     * but the active one, whose subjects live only in that same graph (#317).
+     * A number is either the server's measure of what LANDED (a staged
+     * overwrite keeps the landed count, the same staleness story
+     * `VisualViewSummary.subjectCount` already tells) or, on the active row,
+     * a count of the drawn subjects that survive the typed filter.
+     */
+    readonly subjectCount: number | null;
     readonly active: boolean;
+    readonly staged: ViewRowStaging | null;
 }
 export interface ViewTreeFolder {
     readonly key: string;
@@ -99,17 +119,30 @@ export declare const matchesFilter: (label: string, filterText: string) => boole
 export declare const folderOf: (view: VisualViewSummary) => string;
 export interface ViewTreeInput {
     readonly views: readonly VisualViewSummary[];
+    /**
+     * The pending changeset's view operations, merged over `views` so the rail
+     * shows the reviewer's own staged intent beside landed truth (ADR 0114).
+     * A staged `write-view` at a new path becomes a row; one at a landed path
+     * marks that row and shows what WILL land; a staged `delete-view` marks the
+     * row rather than hiding it. Discarding an operation removes it from this
+     * list, which is the whole revert — the tree derives, it never remembers.
+     */
+    readonly stagedOperations: readonly VisualViewOperation[];
     readonly activeViewId: string;
     /**
-     * How many subjects the active view is drawing right now, from the standing
-     * filter's match set. The server's `subjectCount` was true when the frame
-     * carrying it was sent; this one is true of the canvas beside it, which is
-     * the number the reviewer can check by looking.
+     * The subjects the active view is drawing right now, from the standing
+     * filter's match set, or `null` when nothing is filtering the canvas. The
+     * subjects themselves rather than their count (#317): the active row's
+     * number is how many of them survive the typed filter, which a
+     * pre-computed count could not answer. Unfiltered it is their plain
+     * length — the number the reviewer can check by looking, where the
+     * server's `subjectCount` was only true when the frame carrying it was
+     * sent.
      */
-    readonly activeSubjectCount: number | null;
+    readonly activeSubjects: readonly FilterableSubject[] | null;
     readonly filterText: string;
 }
-export declare const buildViewTree: ({ views, activeViewId, activeSubjectCount, filterText, }: ViewTreeInput) => ViewTree;
+export declare const buildViewTree: ({ views, stagedOperations, activeViewId, activeSubjects, filterText, }: ViewTreeInput) => ViewTree;
 export interface ModelTreeInput {
     readonly nodes: readonly CanvasNode[];
     /**

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

@@ -1,4 +1,4 @@
-import type { VisualViewSummary } from "../adapters/visual/protocol-contract.js";
+import type { VisualViewOperation, VisualViewSummary } from "../adapters/visual/protocol-contract.js";
 import type { CanvasNode } from "../graph-projection.js";
 /**
  * A right-click on a row, in viewport coordinates. The rail reports which row
@@ -14,6 +14,13 @@ export type TreeRowMenu = (row: {
 }) => void;
 export interface ViewTreeProps {
     readonly views: readonly VisualViewSummary[];
+    /**
+     * The pending changeset's view operations, merged over `views` by
+     * `buildViewTree` so staged intent is visible beside landed truth
+     * (ADR 0114). Derived from the changeset at the call site, never stored:
+     * discarding the operation is the revert.
+     */
+    readonly stagedViewOperations: readonly VisualViewOperation[];
     readonly activeViewId: string;
     /** Every subject the workspace declares, filtered or not. */
     readonly nodes: readonly CanvasNode[];
@@ -28,5 +35,7 @@ export interface ViewTreeProps {
     readonly onNewView: () => void;
     readonly onSelectSubject: (id: string) => void;
     readonly onRowMenu: TreeRowMenu;
+    /** A viewer, not an author (#298): the new-view affordance is absent. */
+    readonly readOnly?: boolean;
 }
-export declare function ViewTree({ views, activeViewId, nodes, inViewIds, filterText, collapsed, onFilterChange, onToggle, onSelectView, onClearView, onNewView, onSelectSubject, onRowMenu, }: ViewTreeProps): import("react").JSX.Element;
+export declare function ViewTree({ views, stagedViewOperations, activeViewId, nodes, inViewIds, filterText, collapsed, onFilterChange, onToggle, onSelectView, onClearView, onNewView, onSelectSubject, onRowMenu, readOnly, }: ViewTreeProps): import("react").JSX.Element;

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

@@ -1,5 +1,7 @@
 import type { CanvasEdge, CanvasGraph, CanvasNode } from "../graph-projection.js";
 import { type NestingKind } from "../nesting.js";
+import { type LayoutDirection } from "../layout-direction.js";
+import type { DecorationMap } from "./graph-canvas.js";
 import type { ContextMenuTarget } from "./context-menu-model.js";
 import type { BottomPanelTabId } from "./query-panel.js";
 export interface SelectedElement {
@@ -37,15 +39,59 @@ export interface ConnectionDraft {
 }
 export declare const normalizeSelectedElement: (node: CanvasNode) => SelectedElement;
 export declare const normalizeSelectedRelationship: (edge: CanvasEdge, nodeTitles: ReadonlyMap<string, string>) => SelectedRelationship;
+/**
+ * What the imperative methods read at the moment they are called (#297,
+ * ADR 0118). A getter rather than a captured value, because the pointer is
+ * handed up once and the graph changes under it with every commit - a method
+ * bound to the model that existed at mount time would answer for a model
+ * that is gone.
+ */
+export interface EditorPointerContext {
+    readonly graph: CanvasGraph | null;
+    readonly readOnly: boolean;
+}
+/**
+ * The host's way of pointing at the canvas (#297, ADR 0118): three methods,
+ * each the programmatic twin of a gesture the surface already has - a canvas
+ * tap, a palette pick, the inspector's Connect. Every method answers with
+ * whether it acted; false means nothing moved - the id named nothing, the
+ * model has not arrived, or the mount is a viewer (#298) and the gesture
+ * would have reached for the pen.
+ */
+export interface EditorPointer {
+    readonly select: (subjectId: string) => boolean;
+    readonly openDraft: (options?: {
+        readonly kind?: string;
+    }) => boolean;
+    readonly startConnection: (fromSubjectId: string) => boolean;
+    /**
+     * Replaces the host's per-subject marks wholesale (#314, ADR 0119) - the
+     * map is the unit of exchange, never merged into what stood. Unlike its
+     * siblings this one needs no model and no pen: the marks are client state
+     * drawn when the graph (or its successor) is on screen, and decorating is
+     * reading, so a viewer accepts them too. It answers false only where every
+     * method does - a handle before the shell's first render or after disposal.
+     */
+    readonly setDecorations: (decorations: DecorationMap) => boolean;
+}
+/**
+ * Builds the pointer over the shell's own dispatchers. Nothing here is a
+ * second write path: every method dispatches the same workspace action its
+ * on-screen twin dispatches, so what a host can reach is exactly what a
+ * reviewer can reach, and anything staged still lands through the changeset.
+ */
+export declare const editorPointerFor: (context: () => EditorPointerContext, dispatch: (action: VisualWorkspaceAction) => void, seedDraftKind: (kind: string | undefined) => void, replaceDecorations: (decorations: DecorationMap) => void) => EditorPointer;
 /**
  * The right column's sections, in the order they stack (#249, ADR-free: the
  * design settles the order and nothing derives it).
  *
- * Chat is last because it is pinned at the foot and owns the session's own
- * control - the reviewer ends the conversation beside the conversation, not
- * from a strip that carries identity and nothing else.
+ * The palette leads (#295): it is the tool that makes subjects, and tools
+ * read above inspection - a reviewer reaches for what to add before what is
+ * selected. Chat is last because it is pinned at the foot and owns the
+ * session's own control - the reviewer ends the conversation beside the
+ * conversation, not from a strip that carries identity and nothing else.
  */
-export declare const RIGHT_SECTIONS: readonly ["properties", "changes", "chat"];
+export declare const RIGHT_SECTIONS: readonly ["palette", "properties", "questions", "changes", "chat"];
 export type RightSectionId = (typeof RIGHT_SECTIONS)[number];
 /** How short a section may be dragged before it is just a header. */
 export declare const SECTION_MIN_HEIGHT = 96;
@@ -60,16 +106,26 @@ export declare const CONVERSATION_MIN_WIDTH = 320;
 export declare const CONVERSATION_MAX_WIDTH = 640;
 export interface VisualWorkspaceState {
     /**
-     * The right column: one width, and the sections stacked inside it.
+     * The right column: one width, whether the reviewer has put the whole
+     * column away, and the sections stacked inside it.
      *
-     * There is no longer an open/closed mode. The column is always drawn,
-     * because the sections are collapsible one by one and a reviewer who wants
-     * the canvas back shuts the sections rather than the column - which leaves
-     * three headers saying what is behind them instead of a strip button
-     * saying nothing (#249).
+     * The sections are collapsible one by one, and a reviewer who wants room
+     * shuts sections rather than the column - shut headers say what is behind
+     * them (#249). `hidden` is the further step for the moments that want the
+     * whole canvas - presenting, a projector, a laptop - and the reopen strip
+     * that stands in for the column carries what a shut header would have
+     * said: the unread count and a waiting choice (#294).
      */
     readonly conversation: {
         readonly width: number;
+        /**
+         * Whether the reviewer has put the whole column away (#294). A mode
+         * beside the width rather than a zero width, so the width stays what it
+         * was and reopening restores it - sections and splitters intact. The
+         * presenting moments are exactly when this is used, and presentation
+         * must not cost the reviewer their layout.
+         */
+        readonly hidden: boolean;
         readonly unread: number;
         /** The sections the reviewer has shut. Held as what is CLOSED so a
          * section added later arrives open rather than hidden behind a default
@@ -158,10 +214,18 @@ export interface VisualWorkspaceState {
      * alone - the behaviour that shipped before a view could say.
      */
     readonly nesting: readonly NestingKind[];
+    /**
+     * Which way the active view runs its layers (#274, ADR 0121). A view that
+     * says nothing runs `DEFAULT_DIRECTION`, the same rule `nesting` follows:
+     * silence restores the default rather than carrying the previous view's
+     * answer across.
+     */
+    readonly direction: LayoutDirection;
     readonly layout: "layered";
     readonly showLifecycle: boolean;
     readonly showEvidence: boolean;
     readonly showOwnership: boolean;
+    readonly showNudges: boolean;
 }
 export type VisualWorkspaceAction = {
     readonly type: "section.toggled";
@@ -173,6 +237,8 @@ export type VisualWorkspaceAction = {
 } | {
     readonly type: "conversation.resized";
     readonly width: number;
+} | {
+    readonly type: "conversation.toggled";
 } | {
     readonly type: "viewport.resized";
     readonly viewportWidth: number;
@@ -236,12 +302,15 @@ export type VisualWorkspaceAction = {
 } | {
     readonly type: "nesting.set";
     readonly nesting: readonly NestingKind[];
+} | {
+    readonly type: "direction.set";
+    readonly direction: LayoutDirection;
 } | {
     readonly type: "layout.set";
     readonly layout: "layered";
 } | {
     readonly type: "presentation.toggled";
-    readonly flag: "showLifecycle" | "showEvidence" | "showOwnership";
+    readonly flag: "showLifecycle" | "showEvidence" | "showOwnership" | "showNudges";
     readonly value: boolean;
 } | {
     readonly type: "model.replaced";
@@ -252,6 +321,7 @@ export type VisualWorkspaceAction = {
 export declare const presentationActionsFor: (presentation: {
     readonly layout?: "layered";
     readonly nesting?: readonly NestingKind[];
+    readonly direction?: LayoutDirection;
     readonly showLifecycle?: boolean;
     readonly showEvidence?: boolean;
     readonly showOwnership?: boolean;

package/docs/CONSUMING-YARRAMATE.md

@@ -298,6 +298,46 @@ const editor = mountEditor(document.querySelector('#editor')!, {
 editor.unmount()
 ```
 
+Pass `readOnly: true` to mount a viewer over the same surface — for a frozen
+published snapshot, say ([ADR 0117](adr/0117-a-mounted-editor-can-refuse-the-pen.md)).
+The reviewer still selects, filters, navigates views and reads questions and
+properties (as values, not forms), but every affordance that stages or commits
+is absent rather than disabled: no Add subject, no palette or changes
+sections, no Connect/Delete, no view create/rename/delete, and drags move
+nodes without writing layouts. With no `sections` named, a read-only mount
+defaults to `['properties', 'questions']`. This is a UI posture only — pair it
+with a store that refuses writes; the two defenses are independent.
+`mountEditorWith` takes the same flag as its trailing parameter.
+
+The returned handle can also point at the canvas
+([ADR 0118](adr/0118-the-host-can-point-at-the-canvas.md)):
+`select(subjectId)` selects a concept or relationship exactly as a canvas tap
+would, which also scopes the Open questions section to it;
+`openDraft({ kind })` opens the Add-subject dialog with the kind preselected
+the way a palette pick seeds it (omit `kind` for the plain no-default form);
+and `startConnection(fromSubjectId)` arms the Connect flow from that subject —
+the relationship-with-one-endpoint-fixed affordance an interrogation trigger
+describes. Each returns `false`, rather than throwing, when it moved nothing:
+an id the current model does not name, a model that has not arrived yet, or —
+for `openDraft` and `startConnection` — a read-only mount. These are the
+programmatic twins of tap, palette and Connect, never a second write path:
+anything they lead to still stages through the changeset and commits through
+the same validated batch.
+
+The viewer also accepts per-subject marks
+([ADR 0119](adr/0119-the-viewer-accepts-the-hosts-marks.md)): pass
+`decorations: { [subjectId]: 'added' | 'removed' | 'changed' }` — concepts and
+relationships alike — and the canvas renders them as visual treatments (added
+an eucalyptus border, removed a quiet dashed one, changed ochre; a fault still
+outranks any mark). Comparison semantics stay on your side of the seam: the
+viewer never diffs, it draws the map it is handed, so what a mark means — and
+any legend saying so — is yours. The option is the initial map; the handle's
+`setDecorations(decorations)` replaces it wholesale (never a merge, `{}`
+clears) for a live comparison, works under `readOnly` and before the first
+model frame, and ids the model does not name are silently inert. It shares the
+pointer methods' one false window: before the shell's first render, or after
+unmount.
+
 `store` is the caller's synchronous `SourceStore`; `workspace` is the caller's
 pre-resolved `ResolvedWorkspace`. The local host compiles, projects, filters,
 commits and saves layouts over that store. A changeset's model and view writes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-design-step.schema.json

@@ -533,6 +533,19 @@
               "const": "unscoped-succession"
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace's evidence overlay records observations and every one is a frictionless confirmation: no contradicted, unknown, or not-observed result, and no recorded search (ADR 0107). A discovery that never records anything but success never tested a claim it might fail. The one condition that reads the evidence overlay rather than the compiled graph; where the evaluating consumer supplies no overlay it stays quiet (ADR 0120).",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "unchallenged-evidence"
+            }
+          }
         }
       ]
     },

package/schema/yarramate-interrogation-report.schema.json

@@ -532,6 +532,19 @@
               "const": "unscoped-succession"
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace's evidence overlay records observations and every one is a frictionless confirmation: no contradicted, unknown, or not-observed result, and no recorded search (ADR 0107). A discovery that never records anything but success never tested a claim it might fail. The one condition that reads the evidence overlay rather than the compiled graph; where the evaluating consumer supplies no overlay it stays quiet (ADR 0120).",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "unchallenged-evidence"
+            }
+          }
         }
       ]
     },

package/schema/yarramate-projection.schema.json

@@ -36,6 +36,15 @@
             "$ref": "#/$defs/subjectIdentity"
           }
         },
+        "exclude": {
+          "description": "Subjects this query would otherwise select and the author has taken out: the exception a rule cannot state (#267, ADR 0122). Applied after every other facet and after relationship expansion, so an excluded subject is out whichever way it would have come back in. Naming a subject no facet selects is allowed and inert until the model grows into the rule.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subjectIdentity"
+          }
+        },
         "documents": {
           "type": "array",
           "uniqueItems": true,

package/schema/yarramate-question-catalogue.schema.json

@@ -502,6 +502,19 @@
               "const": "unscoped-succession"
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The workspace's evidence overlay records observations and every one is a frictionless confirmation: no contradicted, unknown, or not-observed result, and no recorded search (ADR 0107). A discovery that never records anything but success never tested a claim it might fail. The one condition that reads the evidence overlay rather than the compiled graph; where the evaluating consumer supplies no overlay it stays quiet (ADR 0120).",
+          "required": [
+            "condition"
+          ],
+          "properties": {
+            "condition": {
+              "const": "unchallenged-evidence"
+            }
+          }
         }
       ]
     },

package/skills/yarramate-architecture/SKILL.md

@@ -267,6 +267,11 @@ request
   -> End or failure: recover, optionally read the transcript, stop, resume
 ```
 
+The canvas itself carries the interview: subjects with open questions wear
+a count chip, and the Open questions panel scopes to the selected subject
+(workspace-scoped questions show when nothing is selected). Landing answers
+through the editor's changeset closes them on the next model frame.
+
 Read [references/visual-conversations.md](references/visual-conversations.md)
 before starting a session. It owns the request builder and its refusals, the
 capability test, the exact commands and documents, the delegated child's prompt