@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/substrate/schema.d.ts

@@ -1,8 +1,8 @@
 import type { Scope } from '../../types.js';
 import type { MemoryDoc } from '../memory-resolver.js';
-export declare const KINDS: readonly ["skill", "reference", "preference"];
+export declare const KINDS: readonly ["knowledge", "preference"];
 export type DocKind = (typeof KINDS)[number];
-/** Is `v` one of the three valid document kinds? */
+/** Is `v` one of the two valid document kinds? */
 export declare function isDocKind(v: unknown): v is DocKind;
 export declare const RUNGS: readonly ["none", "name", "preview", "content"];
 export type Rung = (typeof RUNGS)[number];
@@ -11,10 +11,7 @@ export declare function rungRank(r: Rung): number;
 /** Does rung `r` disclose at least as much as `min`? — e.g.
  *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
-export declare const KIND_DEFAULT_RUNGS: Record<DocKind, {
-    systemPrompt: Rung;
-    fileRead: Rung;
-}>;
+export declare const FALLBACK_RUNG: Rung;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -24,7 +21,7 @@ export type GatePredicate = Record<string, unknown>;
  *  defaults applied. Required fields (`kind`/`when-and-why-to-read`) and
  *  optionals all resolved to concrete typed values. */
 export interface SubstrateSchema {
-    /** Which of the three semantic kinds. */
+    /** Which of the two semantic kinds (knowledge | preference). */
     kind: DocKind;
     /** The read-routing line — a single sentence answering WHEN to read this doc
      *  and WHY it is worth the read: "When <circumstance>, this <kind> should be
@@ -46,6 +43,13 @@ export interface SubstrateSchema {
     /** Optional glob list narrowing the on-read trigger to matching read files.
      *  Absent ⇒ positional trigger only. A single glob is normalized to a 1-list. */
     appliesTo?: string[];
+    /** Optional condition over the READ FILE's own frontmatter — the on-read
+     *  frontmatter trigger (Stream A native rules). Same coercion + predicate
+     *  vocabulary as `gate` (non-null non-array object carried; empty `{}` inert),
+     *  but evaluated by `evalCondition` against the read file's parsed YAML rather
+     *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
+     *  `read-when`. */
+    readWhen?: GatePredicate;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
  *  path-derived identity and body. This single object flows through the whole
@@ -63,10 +67,11 @@ export interface SubstrateDoc extends SubstrateSchema {
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
- *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
- *  falls back to the kind default), so a renderer mapping over many docs never
- *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
 export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
  *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc

package/dist/core/substrate/schema.js

@@ -1,14 +1,23 @@
 // schema.ts — the typed shape of a substrate document's frontmatter, the
-// visibility ladder, the kind→default-rungs table, and the parse/validate
-// function that turns a resolved MemoryDoc into a fully-typed SubstrateDoc with
-// defaults applied. This is the keystone every downstream track (CLI verbs,
-// boot render, on-read render, migrator) builds against — pure and side-effect
-// free. See design-substrate.md §4 (schema) + §9 (defaults).
+// visibility ladder, and the parse/validate function that turns a resolved
+// MemoryDoc into a fully-typed SubstrateDoc. This is the keystone every
+// downstream track (CLI verbs, boot render, on-read render, migrator) builds
+// against — pure and side-effect free. See design-substrate.md §4 (schema).
+//
+// There is NO kind-based default for visibility: the right rung is a
+// case-by-case authoring call, so both rungs are required at authoring time
+// (enforced by `crtr memory write` on create and by `crtr memory lint`). The
+// runtime parser is tolerant by contract (it maps over many docs and must
+// never throw), so a doc missing/with an invalid rung falls back to the neutral
+// floor `none` — a malformed doc renders invisible rather than crashing, and
+// lint flags it. Valid docs never hit the fallback.
 // ---------------------------------------------------------------------------
-// Kinds — the three semantic kinds (design §3). `kind` is data, not a fork.
+// Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
+// playbooks + factual references merged) vs `preference` (behave — standing
+// directives). `kind` is a load-bearing binary, not a content taxonomy.
 // ---------------------------------------------------------------------------
-export const KINDS = ['skill', 'reference', 'preference'];
-/** Is `v` one of the three valid document kinds? */
+export const KINDS = ['knowledge', 'preference'];
+/** Is `v` one of the two valid document kinds? */
 export function isDocKind(v) {
     return typeof v === 'string' && KINDS.includes(v);
 }
@@ -28,46 +37,38 @@ export function rungAtLeast(r, min) {
     return rungRank(r) >= rungRank(min);
 }
 // ---------------------------------------------------------------------------
-// The kind→default-rungs table (design §9). When an author omits a visibility
-// field, its default is a function of `kind` — chosen so the common case is
-// correct with no thought and the migration is behavior-preserving for skills
-// and preferences. One data row per kind, NOT a code fork.
-//
-//   kind         system-prompt-visibility   file-read-visibility
-//   skill        name                       none
-//   preference   preview                    none
-//   reference    none                       preview
+// The neutral fallback rung used only when a doc omits a visibility field or
+// carries an invalid one. NOT a default an author may lean on — authoring-time
+// enforcement requires explicit rungs; this is purely the runtime parser's
+// never-throw floor (a malformed doc renders invisible, and lint flags it).
 // ---------------------------------------------------------------------------
-export const KIND_DEFAULT_RUNGS = {
-    skill: { systemPrompt: 'name', fileRead: 'none' },
-    preference: { systemPrompt: 'preview', fileRead: 'none' },
-    reference: { systemPrompt: 'none', fileRead: 'preview' },
-};
+export const FALLBACK_RUNG = 'none';
 // ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
- *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
- *  falls back to the kind default), so a renderer mapping over many docs never
- *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
 export function parseSubstrateFrontmatter(fm) {
     if (fm === null)
         return null;
     if (!isDocKind(fm.kind))
         return null;
     const kind = fm.kind;
-    const defaults = KIND_DEFAULT_RUNGS[kind];
     return {
         kind,
         whenAndWhyToRead: strField(fm['when-and-why-to-read']),
         shortForm: strField(fm['short-form']),
-        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], defaults.systemPrompt),
-        fileReadVisibility: parseRung(fm['file-read-visibility'], defaults.fileRead),
+        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], FALLBACK_RUNG),
+        fileReadVisibility: parseRung(fm['file-read-visibility'], FALLBACK_RUNG),
         gate: parseGate(fm.gate),
         appliesTo: parseAppliesTo(fm['applies-to']),
+        readWhen: parseGate(fm['read-when']),
     };
 }
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
@@ -95,8 +96,8 @@ export function previewLine(doc) {
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }
-/** Resolve a visibility field to a ladder rung, falling back to the kind
- *  default when absent/invalid. */
+/** Resolve a visibility field to a ladder rung, falling back to the neutral
+ *  floor when absent/invalid. */
 function parseRung(v, fallback) {
     return typeof v === 'string' && RUNGS.includes(v)
         ? v

package/dist/core/tui/host.d.ts

@@ -1,5 +1,5 @@
 import { type Draw, type Rect, type Size } from './draw.js';
-import type { ViewModule, ViewManifest, BannerLevel } from './contract.js';
+import type { ViewCore, TuiPresenter, TextPresenter, KeyHint, BannerLevel } from '../view/contract.js';
 export interface RunViewOptions {
     /** CLI flags forwarded verbatim to the view via host.options. */
     options?: Record<string, string>;
@@ -19,11 +19,19 @@ export interface Chrome {
     subtitle: string | null;
     mode: string | null;
 }
+/** The slice of a view's manifest that drawChrome reads (title + subtitle), plus
+ *  the footer hints lifted from the TuiPresenter's keymap bindings. */
+export interface ChromeManifest {
+    title: string;
+    subtitle?: string;
+    keymap?: KeyHint[];
+}
 /** Draw the host chrome into `draw` and return the content Rect for the view.
  *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
  *  a hairline, and a footer (status left, keymap right) with a severity banner
  *  on the row above it when set. */
-declare function drawChrome(draw: Draw, size: Size, manifest: ViewManifest, c: Chrome, now?: number): Rect;
+declare function drawChrome(draw: Draw, size: Size, manifest: ChromeManifest, c: Chrome, now?: number): Rect;
 export { drawChrome };
-/** Host a view in the alt screen until it quits (or Ctrl-C). */
-export declare function runView<S>(view: ViewModule<S>, opts?: RunViewOptions): Promise<void>;
+/** Host a dual-target ViewCore + TuiPresenter in the alt screen until it quits
+ *  (or Ctrl-C). `text` is the optional text presenter for the piped path. */
+export declare function runCoreView<S>(core: ViewCore<S>, tui: TuiPresenter<S>, text: TextPresenter<S> | null, opts?: RunViewOptions): Promise<void>;