@north-light/crouter 0.3.154

package/dist/types.d.ts

@@ -0,0 +1,297 @@
+export type Scope = 'user' | 'project' | 'builtin';
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly GENERAL: 1;
+    readonly USAGE: 2;
+    readonly NOT_FOUND: 3;
+    readonly AMBIGUOUS: 4;
+    readonly NETWORK: 5;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+export declare const SCHEMA_VERSION = 4;
+export interface OwnerRef {
+    name?: string;
+    email?: string;
+}
+export interface PluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    source?: string;
+    owner?: OwnerRef;
+    kinds?: string[];
+    /** Plugin-root-relative path to one declarative command manifest
+     *  (`commands.json`). When present on an installed, enabled plugin, that
+     *  manifest contributes top-level command branches to the `crtr` tree —
+     *  crtr owns parse/help/render/errors and direct-spawns the plugin's one
+     *  executable per leaf invocation. See `src/core/command-plugins/`. */
+    commands?: string;
+}
+export interface MarketplacePluginEntry {
+    name: string;
+    source: string;
+    version?: string;
+    description?: string;
+    keywords?: string[];
+}
+export interface MarketplaceManifest {
+    name: string;
+    version?: string;
+    owner?: OwnerRef;
+    plugins: MarketplacePluginEntry[];
+}
+export interface ConfigMarketplaceEntry {
+    url: string;
+    ref: string;
+    installed_at: string;
+}
+export interface ConfigPluginEntry {
+    enabled: boolean;
+    source_marketplace?: string;
+    version?: string;
+}
+export interface ConfigConfiguredCliEntry {
+    endpoint: string;
+    authEnvVar?: string;
+}
+export type AutoUpdateMode = 'notify' | 'apply' | false;
+export interface AutoUpdateConfig {
+    crtr: AutoUpdateMode;
+    content: AutoUpdateMode;
+    interval_hours: number;
+}
+/** Host-wide broker pressure thresholds. These are read only from user scope
+ *  by crtrd: project configuration must not change another user's daemon. */
+export interface BrokerThresholdsConfig {
+    /** Surface a broker-pressure warning once the live broker census reaches this count. */
+    warning: number;
+    /** Defer daemon-initiated revives once the live broker census reaches this count. */
+    automaticReviveCap: number;
+}
+export type KeybindingOverrides = Record<string, string[]>;
+/** Compile-time seam for runtime consumers migrating to semantic binding IDs. */
+export type CanvasAction = {
+    kind?: 'crtr';
+    run: string;
+    confirm?: boolean;
+} | {
+    kind: 'keys';
+    keys: string;
+} | {
+    kind: 'menu';
+    items: CanvasMenuItem[];
+} | {
+    kind: 'popup';
+    run: string;
+};
+export interface CanvasMenuItem {
+    key: string;
+    desc: string;
+    action: CanvasAction;
+    confirm?: boolean;
+}
+export type ModelStrength = 'ultra' | 'strong' | 'medium' | 'light';
+export type ModelProvider = 'anthropic' | 'openai';
+export interface ModelLaddersConfig {
+    /** Optional default provider for bare strengths. If unset, runtime falls back
+     *  to CRTR_MODEL_PROVIDER, then anthropic. */
+    defaultProvider?: ModelProvider;
+    anthropic: Record<ModelStrength, string>;
+    openai: Record<ModelStrength, string>;
+}
+/** Launch metadata for one kind (a top-level kind like `developer`, or a full
+ *  sub-kind string like `plan/reviewers/security`) — the settings-file
+ *  replacement for per-kind persona frontmatter. `model`/`tools`/`extensions`
+ *  are launch knobs consumed by `buildLaunchSpec` (Phase 3); `whenToUse` is the
+ *  one-line gloss shown in `node new -h` / `node promote -h`. `availableTo` is
+ *  VISIBILITY-ONLY (never launch validation): the list of top-level kind names
+ *  whose spawn menus surface this sub-kind, `'*'` meaning every kind; omitted
+ *  defaults to the sub-kind's own top-level ancestor (e.g.
+ *  `plan/reviewers/security` defaults to `['plan']`) — this reproduces the
+ *  original sub-persona `availableTo` semantics. A direct launch by full kind
+ *  string is always valid regardless of `availableTo`. */
+export interface KindConfig {
+    model?: string;
+    /** Model override for ORCHESTRATOR mode only, e.g. a kind whose orchestrator
+     *  body warrants a stronger model than its base worker. Selection: base mode
+     *  always uses `model`; orchestrator mode uses `orchestratorModel ?? model`.
+     *  Omit when the kind runs the same model in both modes. */
+    orchestratorModel?: string;
+    tools?: string[];
+    extensions?: string[];
+    whenToUse: string;
+    availableTo?: string[];
+}
+export interface ScopeConfig {
+    schema_version: number;
+    marketplaces: Record<string, ConfigMarketplaceEntry>;
+    plugins: Record<string, ConfigPluginEntry>;
+    configuredClis: Record<string, ConfigConfiguredCliEntry>;
+    auto_update: AutoUpdateConfig;
+    max_panes_per_window: number;
+    brokerThresholds: BrokerThresholdsConfig;
+    /** Ring a short completion sound in the attach viewer when the node you are
+     *  watching finishes a turn and hands control back (the Claude-Code Stop-hook
+     *  ding). Only ever fires inside a live viewer pane — a headless/background
+     *  node with no viewer attached is silent regardless. Default true. */
+    completion_bell: boolean;
+    /** How many trailing refresh-yield CYCLES the attach viewer renders at full
+     *  fidelity. Older cycles are condensed (cycle dividers plus whatever
+     *  `condensed_history` admits) and frozen into a flat line block:
+     *  no tool components are built for them, and they never re-wrap on resize.
+     *  Tool calls and results measure ~63% of a transcript's rendered lines and
+     *  ~69% of its build time, so this is the dominant cost of attaching to a long
+     *  multi-cycle node. Full detail for every cycle stays in the session file.
+     *  Minimum 1 (the live cycle is never condensed). Default 2. */
+    live_cycles: number;
+    /** What survives from a CONDENSED cycle (one older than the trailing
+     *  `live_cycles`). The cycle dividers always remain as seams so you can see
+     *  that older cycles exist; this chooses which of their messages are kept:
+     *  `none` (default) drops every message, `user` keeps only your prompts,
+     *  `agent` keeps only the assistant's prose plus compaction/branch summaries,
+     *  `both` keeps both. Tool calls and results are never kept. Full detail for
+     *  every cycle stays in the session file. */
+    condensed_history: CondensedHistoryMode;
+    keybindings: KeybindingOverrides;
+    modelLadders: ModelLaddersConfig;
+    /** The kind registry (spec §1.5): kind existence + launch knobs, keyed by
+     *  full kind string (top-level e.g. `developer`, or sub-kind e.g.
+     *  `plan/reviewers/security`). Builtins ship a default registry via
+     *  `defaultScopeConfig()`; user/project `config.json` adds or shadows
+     *  entries at the same scope precedence as the rest of `ScopeConfig`. */
+    kinds: Record<string, KindConfig>;
+    /** Named remote-canvas targets for `crtr surface attach to <id> --canvas
+     *  <name>`, `crtr node inspect list/show --canvas <name>`, and `crtr canvas
+     *  browse --canvas <name>` — registered/managed via `crtr canvas config
+     *  add/list/show/remove` and selected durably via `crtr canvas use`. Unset
+     *  via `sys config set` — not in `TOP_LEVEL_KEYS`. */
+    remoteCanvas: RemoteCanvasConfig;
+    /** Extra env-var names/globs a scope explicitly admits across the broker
+     *  spawn-env boundary (`buildBrokerEnv`, `core/runtime/spawn-env.ts`) — the
+     *  "I accept this crosses as a shell-visible credential" escape hatch for a
+     *  bespoke provider key, a deliberate `GIT_*` var, or a credentialed proxy.
+     *  Default empty; merged additively across project > profile > user >
+     *  builtin scope precedence, same as the rest of `ScopeConfig`. */
+    spawnEnv?: {
+        allow?: string[];
+    };
+}
+/** One remote canvas target: where to relay-attach and how to find its
+ *  bearer token. The token itself is NEVER stored here — only a ref into the
+ *  0600 secrets store, resolved at connect time by `resolveRemoteCanvasTarget`
+ *  (`src/core/view/remote-canvas-target.ts`) via `getRelayToken`
+ *  (`src/core/secrets.ts`). */
+export interface RemoteCanvasTarget {
+    previewEndpoint: string;
+    /** Name/ref under which the raw token is stored in secrets.json — NEVER the
+     *  token itself. Resolved via `getRelayToken` (`core/secrets.ts`) at connect
+     *  time. Defaults to the target name at creation but is a distinct field so
+     *  a future rename doesn't orphan the secret. */
+    relayTokenRef: string;
+    cpOrigin?: string;
+}
+export interface RemoteCanvasConfig {
+    targets: Record<string, RemoteCanvasTarget>;
+}
+export interface ScopeState {
+    marketplaces: Record<string, {
+        last_updated?: string;
+    }>;
+    plugins: Record<string, {
+        last_updated?: string;
+    }>;
+    last_self_check?: string;
+    bootstrap_done?: boolean;
+    /** The name of the remote canvas target `crtr canvas use` last selected
+     *  (see `RemoteCanvasConfig`), or `null`/omitted for local. Read by
+     *  `resolveCanvasSource` (`core/canvas/source.ts`) as the durable fallback
+     *  when a command's own `--canvas` flag is absent. */
+    activeCanvas?: string | null;
+}
+export interface SubagentFrontmatter {
+    name: string;
+    description?: string;
+    /** Tool allow-list (pi tool names). Passed through to pi via `--tools`. */
+    tools?: string[];
+    /** Model pattern/id passed to the agent CLI via `--model`. */
+    model?: string;
+}
+export interface Subagent {
+    name: string;
+    /** Plugin the subagent belongs to, or the sentinel '_' for a scope-root
+     *  agent stored at `<scope-root>/agents/<name>.md`. */
+    plugin: string;
+    scope: Scope;
+    /** Absolute path to the agent's .md file. */
+    path: string;
+    frontmatter: SubagentFrontmatter;
+    /** Markdown body — used as the spawned agent's appended system prompt. */
+    systemPrompt: string;
+}
+export interface InstalledPlugin {
+    name: string;
+    scope: Scope;
+    root: string;
+    manifest: PluginManifest;
+    enabled: boolean;
+    builtin?: boolean;
+    sourceMarketplace?: string;
+    version?: string;
+}
+export interface InstalledMarketplace {
+    name: string;
+    scope: Scope;
+    root: string;
+    manifest: MarketplaceManifest;
+    url: string;
+    ref: string;
+}
+/** The on-disk manifest at `~/.crouter/profiles/<slug>-<id>/profile.json`
+ *  (spec §2.1). A profile is an agent identity defined at the user root: it
+ *  names N project directories and owns its own `memory/` store. `projects`
+ *  are absolute, real-path-resolved directories in manifest order — the
+ *  pointer set `findProjectScopeRoots` walks (Phase 5), after the node's own
+ *  cwd. `name` is the mutable display name (and the gateable `profile` subject
+ *  field, Phase 6); `<slug>-<id>` in the directory name is the stable id and
+ *  never changes on rename. See `src/core/profiles/manifest.ts` for every
+ *  read/write of this file — it is the sole owner of path resolution and
+ *  mutation. */
+export interface ProfileManifest {
+    schema_version: number;
+    name: string;
+    projects: string[];
+    created_at: string;
+    last_used_at: string | null;
+}
+export declare const PLUGIN_MANIFEST_DIR = ".crouter-plugin";
+export declare const PLUGIN_MANIFEST_FILE = "plugin.json";
+export declare const MARKETPLACE_MANIFEST_DIR = ".crouter-marketplace";
+export declare const MARKETPLACE_MANIFEST_FILE = "marketplace.json";
+export declare const CRTR_DIR_NAME = ".crouter";
+export declare const CONFIG_FILE = "config.json";
+export declare const STATE_FILE = "state.json";
+export declare const AGENTS_DIR = "agents";
+export declare const PROFILE_DIR = "profiles";
+export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
+/** Trailing cycles the attach viewer keeps at full fidelity (see `live_cycles`). */
+export declare const DEFAULT_LIVE_CYCLES = 2;
+/** Messages kept from a condensed cycle (see `condensed_history`). */
+export declare const CONDENSED_HISTORY_MODES: readonly ["none", "user", "agent", "both"];
+export type CondensedHistoryMode = (typeof CONDENSED_HISTORY_MODES)[number];
+export declare const DEFAULT_CONDENSED_HISTORY: CondensedHistoryMode;
+export declare function defaultScopeConfig(): ScopeConfig;
+/** No remote canvas targets are configured out of the box — every one is
+ *  registered via `crtr canvas config add` (see `RemoteCanvasConfig`). */
+export declare function defaultRemoteCanvasConfig(): RemoteCanvasConfig;
+/** The builtin kind registry (spec §1.5): the built-in defaults for every
+ *  top-level kind and its sub-persona kinds. `whenToUse`/`model` are the
+ *  base-worker defaults; `orchestratorModel` optionally raises the default
+ *  for a coordinating persona. Roadmap-shaping guidance is orchestrator-only —
+ *  an orchestrator-gated memory doc keyed to the kind, not baked into the
+ *  registry entry. Sub-persona `availableTo` is
+ *  omitted where it only reproduces the default (its own top-level
+ *  ancestor) — `product/teardown` is included explicitly below for parity
+ *  even though its value equals the default. */
+export declare function defaultKindsConfig(): Record<string, KindConfig>;
+export declare function defaultModelLaddersConfig(): ModelLaddersConfig;
+export declare function defaultScopeState(): ScopeState;

package/dist/types.js

@@ -0,0 +1,153 @@
+export const ExitCode = {
+    SUCCESS: 0,
+    GENERAL: 1,
+    USAGE: 2,
+    NOT_FOUND: 3,
+    AMBIGUOUS: 4,
+    NETWORK: 5,
+};
+export const SCHEMA_VERSION = 4;
+export const PLUGIN_MANIFEST_DIR = '.crouter-plugin';
+export const PLUGIN_MANIFEST_FILE = 'plugin.json';
+export const MARKETPLACE_MANIFEST_DIR = '.crouter-marketplace';
+export const MARKETPLACE_MANIFEST_FILE = 'marketplace.json';
+export const CRTR_DIR_NAME = '.crouter';
+export const CONFIG_FILE = 'config.json';
+export const STATE_FILE = 'state.json';
+// Subagent definitions live as flat `<name>.md` files under `<root>/agents/`,
+// for both scope roots and plugins.
+export const AGENTS_DIR = 'agents';
+// Profile stores live as `<slug>-<id>/` dirs under `<user-scope-root>/profiles/`
+// (never a project/builtin scope — profiles are a user-root-only concept).
+export const PROFILE_DIR = 'profiles';
+export const DEFAULT_MAX_PANES_PER_WINDOW = 3;
+/** Trailing cycles the attach viewer keeps at full fidelity (see `live_cycles`). */
+export const DEFAULT_LIVE_CYCLES = 2;
+/** Messages kept from a condensed cycle (see `condensed_history`). */
+export const CONDENSED_HISTORY_MODES = ['none', 'user', 'agent', 'both'];
+export const DEFAULT_CONDENSED_HISTORY = 'none';
+export function defaultScopeConfig() {
+    return {
+        schema_version: SCHEMA_VERSION,
+        marketplaces: {},
+        plugins: {},
+        configuredClis: {},
+        auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
+        max_panes_per_window: DEFAULT_MAX_PANES_PER_WINDOW,
+        brokerThresholds: { warning: 128, automaticReviveCap: 256 },
+        completion_bell: true,
+        live_cycles: DEFAULT_LIVE_CYCLES,
+        condensed_history: DEFAULT_CONDENSED_HISTORY,
+        keybindings: {},
+        modelLadders: defaultModelLaddersConfig(),
+        kinds: defaultKindsConfig(),
+        remoteCanvas: defaultRemoteCanvasConfig(),
+        spawnEnv: { allow: [] },
+    };
+}
+/** No remote canvas targets are configured out of the box — every one is
+ *  registered via `crtr canvas config add` (see `RemoteCanvasConfig`). */
+export function defaultRemoteCanvasConfig() {
+    return { targets: {} };
+}
+/** The builtin kind registry (spec §1.5): the built-in defaults for every
+ *  top-level kind and its sub-persona kinds. `whenToUse`/`model` are the
+ *  base-worker defaults; `orchestratorModel` optionally raises the default
+ *  for a coordinating persona. Roadmap-shaping guidance is orchestrator-only —
+ *  an orchestrator-gated memory doc keyed to the kind, not baked into the
+ *  registry entry. Sub-persona `availableTo` is
+ *  omitted where it only reproduces the default (its own top-level
+ *  ancestor) — `product/teardown` is included explicitly below for parity
+ *  even though its value equals the default. */
+export function defaultKindsConfig() {
+    return {
+        general: {
+            whenToUse: 'Anything else — the catch-all worker for a task that does not fit a specialist kind.',
+            model: 'anthropic/strong',
+        },
+        explore: {
+            whenToUse: 'Gather current-state evidence about unfamiliar code or existing architecture — read-only code-path research with concrete file:line support. Diagnosis or recommendations belong to advisor, target architecture to design, required behavior or acceptance criteria to spec, and implementation decomposition to plan.',
+            model: 'openai/light',
+            orchestratorModel: 'anthropic/strong',
+        },
+        developer: {
+            whenToUse: 'Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.',
+            model: 'openai/medium',
+            orchestratorModel: 'anthropic/strong',
+        },
+        design: {
+            whenToUse: 'Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.',
+            model: 'anthropic/strong',
+        },
+        plan: {
+            whenToUse: 'Break work into steps — turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.',
+            model: 'anthropic/strong',
+            orchestratorModel: 'anthropic/strong',
+        },
+        spec: {
+            whenToUse: 'Collaborate with the user to discover what to build, then write the spec — behavior, non-goals, interfaces, edge cases, testable acceptance criteria.',
+            model: 'anthropic/strong',
+        },
+        product: {
+            whenToUse: 'Discover the real user need behind a request and define the product experience that meets it — use cases, how it should feel and look, grounded in how comparable products solve it. Hands off to spec.',
+            model: 'anthropic/strong',
+        },
+        review: {
+            whenToUse: 'Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.',
+            model: 'openai/medium',
+            orchestratorModel: 'openai/strong',
+        },
+        advisor: {
+            whenToUse: 'Debug failures, investigate why something is broken or misbehaving, diagnose live/runtime issues, or give engineering advice and second opinions — reason from evidence and recommend the next move. Use advisor (not explore) whenever the task is to find out what is going wrong.',
+            model: 'anthropic/strong',
+        },
+        'plan/reviewers/requirements-coverage': {
+            whenToUse: 'every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps',
+            model: 'medium',
+        },
+        'plan/reviewers/pattern-consistency': {
+            whenToUse: "the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts",
+            model: 'medium',
+        },
+        'plan/reviewers/code-smells': {
+            whenToUse: 'nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts',
+            model: 'medium',
+        },
+        'plan/reviewers/security': {
+            whenToUse: 'input validation, injection surfaces, auth/authz gaps, data exposure, races; reports only validated concrete exploit paths and asks the human about material unknown threat-model assumptions',
+            model: 'medium',
+        },
+        'plan/reviewers/architecture-fit': {
+            whenToUse: "proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries",
+            model: 'medium',
+        },
+        'spec/requirements': {
+            whenToUse: 'Derive testable EARS requirements from a finished, approved design — in isolation, from the rendered design text alone.',
+            model: 'medium',
+        },
+        'product/teardown': {
+            whenToUse: 'Tear down ONE comparable product against a specific job-to-be-done — how it solves it, where it succeeds and fails its users, and what to borrow, avoid, or differentiate from.',
+            model: 'medium',
+            availableTo: ['product'],
+        },
+    };
+}
+export function defaultModelLaddersConfig() {
+    return {
+        anthropic: {
+            ultra: 'anthropic/claude-fable-5:xhigh',
+            strong: 'anthropic/claude-opus-5:medium',
+            medium: 'anthropic/claude-sonnet-5:xhigh',
+            light: 'anthropic/claude-haiku-4-5:high',
+        },
+        openai: {
+            ultra: 'openai-codex/gpt-5.6-sol:max',
+            strong: 'openai-codex/gpt-5.6-sol:high',
+            medium: 'openai-codex/gpt-5.6-terra:medium',
+            light: 'openai-codex/gpt-5.6-luna:low',
+        },
+    };
+}
+export function defaultScopeState() {
+    return { marketplaces: {}, plugins: {} };
+}

package/dist/web/ViewChrome.d.ts

@@ -0,0 +1,7 @@
+import type { JSX, ReactNode } from 'react';
+import type { ChromeState } from '../core/view/contract.js';
+export declare function ViewChrome({ chrome, title, children }: {
+    chrome: ChromeState;
+    title: string;
+    children: ReactNode;
+}): JSX.Element;

package/dist/web/ViewChrome.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { deriveState } from '../core/view/chrome.js';
+const CHIP_LABEL = {
+    working: 'working',
+    blocked: 'blocked',
+    attention: 'attention',
+    ready: 'ready',
+    idle: 'idle',
+};
+const CHIP_DOT = {
+    working: 'bg-blue-500',
+    blocked: 'bg-red-500',
+    attention: 'bg-amber-500',
+    ready: 'bg-green-500',
+    idle: 'bg-slate-400',
+};
+const BANNER_BAR = {
+    info: 'bg-slate-100 text-slate-800 border-slate-300',
+    action: 'bg-amber-100 text-amber-900 border-amber-300',
+    error: 'bg-red-100 text-red-900 border-red-300',
+};
+export function ViewChrome({ chrome, title, children }) {
+    // deriveState's contract: an explicit interaction mode overrides the derived
+    // chip, and each target's renderer applies that precedence. Web keeps the mode
+    // as its own header pill (the §4.1 web idiom) AND lets it win the chip.
+    const chip = chrome.mode ? 'attention' : deriveState(chrome);
+    return (_jsxs("div", { className: "min-h-screen bg-white text-slate-900", children: [_jsxs("header", { className: "flex items-center gap-3 border-b border-slate-200 px-4 py-2", children: [_jsx("h1", { className: "font-mono text-sm font-semibold", children: title }), chrome.subtitle ? (_jsxs("span", { className: "font-mono text-xs text-slate-400", children: ["\u00B7 ", chrome.subtitle] })) : null, chrome.mode ? (_jsx("span", { className: "rounded-full bg-slate-800 px-2 py-0.5 text-xs text-white", children: chrome.mode })) : null, _jsxs("span", { className: "ml-auto flex items-center gap-2 text-xs text-slate-500", children: [chrome.busy ? (_jsx("span", { className: "inline-block h-3 w-3 animate-spin rounded-full border-2 border-slate-300 border-t-slate-600" })) : null, _jsx("span", { className: `inline-block h-2 w-2 rounded-full ${CHIP_DOT[chip]}` }), _jsx("span", { children: CHIP_LABEL[chip] })] })] }), chrome.banner ? (_jsx("div", { className: `border-b px-4 py-1.5 font-mono text-xs ${BANNER_BAR[chrome.banner.level]}`, children: chrome.banner.msg })) : null, _jsx("main", { className: "px-4 py-3", children: children }), chrome.status ? (_jsx("footer", { className: "border-t border-slate-200 px-4 py-1.5 font-mono text-xs text-slate-500", children: chrome.status })) : null] }));
+}

package/dist/web/ViewPane.d.ts

@@ -0,0 +1,39 @@
+import type { JSX, FunctionComponent } from 'react';
+import type { ViewCore, ChromeState } from '../core/view/contract.js';
+import { type IntentTap } from './runtime.js';
+type ViewPropsWeb = {
+    state: unknown;
+    dispatch: (intent: string, payload?: unknown) => void;
+    chrome: ChromeState;
+};
+type WebComponent = FunctionComponent<ViewPropsWeb>;
+export interface UseViewCoreOptions {
+    /** Frozen options map handed to core.init. */
+    options?: Record<string, string>;
+    /** Bridge endpoint for the HTTP transport; defaults to /__crtr/source. */
+    endpoint?: string;
+    /** The host TAP (§5): observe/intercept dispatched intents. */
+    onIntent?: IntentTap;
+}
+export interface ViewCoreHandle {
+    state: unknown;
+    chrome: ChromeState;
+    dispatch: (intent: string, payload?: unknown) => void;
+    /** Force an immediate refresh — the seam the shell calls on an SSE
+     *  invalidation (Wave 3). */
+    refresh: () => void;
+}
+/** Run a view core client-side and bind it to React. Returns the live state +
+ *  chrome + a dispatch (and a refresh seam). The onIntent tap is read fresh on
+ *  every render, so a parent can change it without tearing down the view. */
+export declare function useViewCore(core: ViewCore, opts?: UseViewCoreOptions): ViewCoreHandle;
+/** Host any dual-target view as a React component: its web component wrapped in
+ *  <ViewChrome>, driven by useViewCore. Pass onIntent to tap its intents. */
+export declare function ViewPane({ core, View, options, endpoint, onIntent }: {
+    core: ViewCore;
+    View: WebComponent;
+    options?: Record<string, string>;
+    endpoint?: string;
+    onIntent?: IntentTap;
+}): JSX.Element;
+export {};

package/dist/web/ViewPane.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// ViewPane.tsx — the React surface for a dual-target view. <ViewPane> and its
+// useViewCore hook are the composable replacement for the deleted imperative
+// mount(): the shell hosts many views as ordinary React components instead of
+// imperative createRoot calls.
+//
+// useViewCore wraps a createViewStore (runtime.tsx) — the framework-free dispatch
+// loop — with the React lifecycle: it creates the store once (a ref), keeps the
+// onIntent TAP fresh per render WITHOUT restarting, re-renders off the store's
+// external-store surface (useSyncExternalStore), and starts/stops the auto-poll
+// on mount/unmount.
+//
+// <ViewPane> = useViewCore + <ViewChrome> + the view's web component. When
+// onIntent is undefined a ViewPane is byte-identical to the old standalone mount
+// — the hosted view never knows it is in a shell.
+import { createElement, useEffect, useRef, useSyncExternalStore } from 'react';
+import { ViewChrome } from './ViewChrome.js';
+import { createViewStore } from './runtime.js';
+/** Run a view core client-side and bind it to React. Returns the live state +
+ *  chrome + a dispatch (and a refresh seam). The onIntent tap is read fresh on
+ *  every render, so a parent can change it without tearing down the view. */
+export function useViewCore(core, opts = {}) {
+    const storeRef = useRef(null);
+    if (storeRef.current === null) {
+        storeRef.current = createViewStore(core, { options: opts.options, endpoint: opts.endpoint });
+    }
+    const store = storeRef.current;
+    // Keep the TAP fresh without recreating the store (which would restart the
+    // dispatch loop and lose state).
+    store.onIntent = opts.onIntent;
+    useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion);
+    useEffect(() => {
+        store.start();
+        return () => store.stop();
+    }, [store]);
+    return {
+        state: store.getState(),
+        chrome: store.getChrome(),
+        dispatch: store.dispatch,
+        refresh: store.refresh,
+    };
+}
+/** Host any dual-target view as a React component: its web component wrapped in
+ *  <ViewChrome>, driven by useViewCore. Pass onIntent to tap its intents. */
+export function ViewPane({ core, View, options, endpoint, onIntent }) {
+    const { state, chrome, dispatch } = useViewCore(core, { options, endpoint, onIntent });
+    return (_jsx(ViewChrome, { chrome: chrome, title: core.manifest.title, children: createElement(View, { state, dispatch, chrome }) }));
+}

package/dist/web/index.d.ts

@@ -0,0 +1,8 @@
+export { ViewPane, useViewCore } from './ViewPane.js';
+export type { UseViewCoreOptions, ViewCoreHandle } from './ViewPane.js';
+export { createViewStore } from './runtime.js';
+export type { ViewStore, ViewStoreOptions, IntentTap } from './runtime.js';
+export { ViewChrome } from './ViewChrome.js';
+export { Loading, Empty, ErrorState, NotReady } from './states.js';
+export { findRefTokens, formatRefToken, findRefTokenAtCaret, } from '../core/memory/inline-ref-grammar.js';
+export type { RefToken, RefCaretToken } from '../core/memory/inline-ref-grammar.js';

package/dist/web/index.js

@@ -0,0 +1,22 @@
+// index.ts — the public barrel for crtr's web runtime, published as the package
+// `exports` subpath `@north-light/crouter/web` (→ ./dist/web/index.js).
+//
+// A dual-target view's `web.jsx` imports the shared four-state vocabulary +
+// (if it needs them) the chrome wrapper from here, via that stable specifier —
+// NOT a relative path from builtin-views, which would break for user/project
+// views living outside the package tree. The shell + dev Vite resolve this
+// subpath against crouter's own built barrel.
+//
+// The web shell composes views via <ViewPane>/useViewCore (the React surface)
+// over createViewStore (the framework-free dispatch loop + the onIntent tap +
+// the refresh() SSE seam).
+export { ViewPane, useViewCore } from './ViewPane.js';
+export { createViewStore } from './runtime.js';
+export { ViewChrome } from './ViewChrome.js';
+export { Loading, Empty, ErrorState, NotReady } from './states.js';
+// Inline memory-reference grammar (spec §4.1) — zero-import, browser-safe.
+// The web client imports THIS re-export (never a mirrored copy) so its
+// highlighting/completion use byte-identical logic to the broker's
+// resolution/guidance and the terminal attach viewer. See
+// `src/core/memory/inline-ref-grammar.ts` for the algorithm.
+export { findRefTokens, formatRefToken, findRefTokenAtCaret, } from '../core/memory/inline-ref-grammar.js';

package/dist/web/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { ViewCore, ChromeState } from '../core/view/contract.js';
+/** Host-level pre-dispatch hook: observes every dispatched intent + its payload
+ *  against a snapshot of state, before the view's own handler runs. The shell
+ *  taps the small documented shell-intent vocabulary (`activate`, `open`) and
+ *  lets everything else pass through untouched. */
+export type IntentTap = (name: string, payload: unknown, state: unknown) => void;
+export interface ViewStoreOptions {
+    /** Frozen options map handed to core.init (e.g. forwarded --target). */
+    options?: Record<string, string>;
+    /** Bridge endpoint for the HTTP transport; defaults to /__crtr/source. */
+    endpoint?: string;
+    /** The host TAP (§5). Omit ⇒ standalone, byte-identical to no shell. */
+    onIntent?: IntentTap;
+}
+export interface ViewStore {
+    /** Snapshot of the current view state (read after a subscribe fires). */
+    getState(): unknown;
+    /** Snapshot of the current chrome record. */
+    getChrome(): ChromeState;
+    /** Dispatch a named intent — runs the TAP, then the core handler. */
+    dispatch(intent: string, payload?: unknown): Promise<void>;
+    /** Force an immediate, busy-guarded refresh (auto-poll cb + the SSE seam). */
+    refresh(): void;
+    /** External-store subscribe (for useSyncExternalStore). */
+    subscribe(listener: () => void): () => void;
+    /** Monotonic version the external store snapshots on. */
+    getVersion(): number;
+    /** Run the first refresh + start the refreshMs auto-poll. Idempotent. */
+    start(): void;
+    /** Stop the auto-poll. Idempotent. */
+    stop(): void;
+    /** The host TAP — mutable so the React layer keeps it fresh per render
+     *  WITHOUT restarting the store. */
+    onIntent?: IntentTap;
+}
+/** Build the running store for one view (its core + the HTTP transport). The
+ *  React layer (useViewCore) owns lifecycle (start on mount, stop on unmount)
+ *  and re-renders off subscribe/getVersion; this factory is React-free. */
+export declare function createViewStore(core: ViewCore, opts?: ViewStoreOptions): ViewStore;