@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/definitions/model.ts

@@ -0,0 +1,238 @@
+/**
+ * The MODEL: the served definition shapes and the small kind/word normalizers that
+ * belong to them. Split from definitions.ts 2026-08-29.
+ */
+
+export interface UnoverseDefinition {
+  unoverse: string;
+  /** `app` is the app kind's IN-CODE name (the 2026-08-23 rename, finished in code
+   *  2026-08-28); stored words are unchanged (DB item kind, registry rows, and the
+   *  manifest `type` field still say "template" until their own migration).
+   *  `template` is the Template Model kind (UNOVERSE_TEMPLATE_MODEL.md). */
+  kind: "component" | "app" | "atom" | "template";
+  name: string;
+  /** TEMPLATES (§9b RULED 2026-08-29): the compiled SECTIONS of each state's
+   *  layout — one entry per `static:` / `copywriter:` / `director:` line, in
+   *  arrangement order. `static`/`copywriter` link a component (face = its
+   *  basename); the ONE `director` section is where deliveries land (face = its
+   *  `state:` pin, else the owning state's name). Studio's table and seeding read
+   *  this; the wire layouts carry the expanded ComponentSlots. */
+  sections?: Record<
+    string,
+    {
+      kind: "static" | "copywriter" | "director";
+      face: string;
+      /** Linked sections: the authored path (components/masthead). A DIRECTOR section
+       *  with a component is a SEARCH PLACE (§9e, one word since 2026-09-02); without
+       *  one it is a DELIVERY band. */
+      component?: string;
+      /** Linked sections: the resolvable scoped ref (email-digest/masthead). */
+      ref?: string;
+      /** SEARCH places (§9e rule 10d): the DERIVED question — never authored. Stamped at
+       *  fill time from the first voice that speaks: the writer's headings (items), the
+       *  page's pool (galleries), the component's own contract, or the guest's ask.
+       *  Present on the wire only after derivation; a layout carrying one fails to load. */
+      ask?: string;
+      /** SEARCH places: which `object_type`s may answer, as the six `include*` flags
+       *  (`ranking.ts`). A day is made of SERVICES; nothing should draw a need, a skill or
+       *  an app into a moment. APPS ARE ALWAYS OFF on this lane, whatever is listed: the
+       *  page's searches are SILENT — no app unlocked, no tool minted, no card lane, no
+       *  director woken — because otherwise every place would rain cards onto the screen
+       *  while the page was still assembling itself. */
+      include?: string[];
+      /** The previewed components' own mock values (`preview ?? default` per prop),
+       *  keyed by REF — a linked part's one component, or each of the director's
+       *  stand-ins. A preview host seeds instances with these the way the Components
+       *  screen does; without them everything draws as ghosts and a finished arrangement
+       *  reads as a broken one. Never used at runtime: a delivery fills the instance. */
+      seeds?: Record<string, Record<string, unknown>>;
+      /** Delivery bands only (a director section with no component). */
+      state?: string;
+      rules?: string;
+      preview?: string[];
+      /** Both director modes: how many the director keeps — the ONE cap word. */
+      pick?: number;
+      /** Search places: which search answers (authored; derived when absent). */
+      type?: "discovery" | "intent";
+      /** An items place (§9e rule 10c): the writer shapes min–max items, each heading
+       *  arriving with its own search. */
+      items?: { min: number; max: number };
+    }[]
+  >;
+  /** TEMPLATES: Studio preview mocks per slot — interface refs, each rendering its
+   *  own defaults (the interface-model rule: mocks are the interface's OWN defaults,
+   *  never authored preview data). From the template's manifest.yaml. */
+  preview?: Record<string, string[]>;
+  /** Source basename for FILE definitions (atoms) — the identity refs resolve by. */
+  file?: string;
+  /** The client org it belongs to (server-injected from its folder, never
+   *  hand-written) — also names its theme (`<org>/light`). Design-system components
+   *  and atoms are universal and carry no org; an ORG component (the client's own
+   *  microapp, `rx/orgs/<org>/components/`) carries its org and is org-private. */
+  org?: string;
+  category?: string;
+  /** Human display name ("Bank Transfer"); falls back to `name` (the id). */
+  title?: string;
+  description?: string;
+  /** COMPOSITION CONTEXT (UNOVERSE_AUTHORING §3b): what the definition says about filling
+   *  the WHOLE of it — never drawn, never discovery copy. STAMPED BY THE LOADER from the
+   *  envelope's own `description` when a manifest's discovery copy takes that key. */
+  composition?: string;
+  /** TEMPLATES: the spatial-discovery selection text — ranked against user intent
+   *  by findIntent, exactly like a node's whenToUse in the node catalog. Write it
+   *  outcome-first in the user's vocabulary (packages/docs/nodes/14-node-discoverability.md);
+   *  `description` stays the human "what it is". When present it REPLACES
+   *  description in the embedded text. */
+  whenToUse?: string;
+  props?: Record<string, unknown>;
+  /** COMPONENTS (render contract): the composed `state` block. The manifest's arrival
+   *  `defaultState` seeds it so the SDK renders that face on arrival (merged beneath
+   *  live data). Server-composed from the manifest, never hand-written. */
+  state?: Record<string, unknown>;
+  /** COMPONENTS: projected capability flag — true iff the component folder carries a
+   *  manifest.json (spatial-capable). Derived from presence, never authored in a def. */
+  spatial?: boolean;
+  /** Display icon URL (from the manifest; catalogs/drawers only). */
+  icon?: string;
+  /** COMPONENTS: manifest version (display only). */
+  version?: string;
+  /** COMPONENTS: credential types a lifecycle hook needs, by name. The canvas offers the
+   *  same picker a node gets; the value is resolved server-side and never in this folder. */
+  credentials?: string[];
+  root: unknown;
+  /** TEMPLATE LAYOUTS (name-sync): present only when the template folder carries
+   *  MULTIPLE layouts/ files. Each entry is a fully composed arrangement; the SDK
+   *  presents the layout whose name matches the latest surfaced component view,
+   *  falling back to `defaultLayout` (the manifest's `layout`). One-layout
+   *  templates never carry this — byte-for-byte the classic behavior. */
+  layouts?: Record<string, unknown>;
+  defaultLayout?: string;
+  /** THE APP'S TEMPLATES (the container noun folded into templates, 2026-08-28):
+   *  the manifest's `templates:` block, straight through. Each entry is a PLACE the
+   *  layout positions by name (`type: Template, name: courses`) and owns the width
+   *  of. `use:` mounts a template definition (its own states/shapes/slots run
+   *  there), with the per-USE director grant beside it; the legacy holder form
+   *  (interface / states) remains a template with one shape. `workflow`/`query`
+   *  are the place's source, served as data. */
+  templates?: Record<
+    string,
+    {
+      /** Mount this template definition here (bare shelf name or `<org>/<name>`) —
+       *  the holder grammar: a place names what it holds (`interface:` for one
+       *  component, `template:` for a mounted template). Unmoved by the 2026-09-01
+       *  rename: here the word names a TEMPLATE, which is what it means. */
+      template?: string;
+      /** STAMPED BY THE LOADER for a state-held mount: the mounted template's own
+       *  state names — the views whose arrival counts as this state's claim. */
+      claims?: string[];
+      /** Director-at-use: duties + rules granted for THIS placement. */
+      director?: Record<string, unknown>;
+      /** This place's own Studio preview seeds (interface refs). */
+      preview?: string[];
+      /** This place's own FEED, one block: workflow + trigger + autoTrigger +
+       *  inputSchema (the app-level `binding` word, applied per place; the first
+       *  carrier lifts to the app level for the composer). */
+      binding?: { workflow?: string; trigger?: string; autoTrigger?: boolean; inputSchema?: Record<string, unknown> };
+      /** Legacy holder shorthand: a one-state place holding this interface. */
+      interface?: string;
+      /** Legacy holder states — each holds an interface; tabs switch between them. */
+      states?: Record<string, { interface?: string; state?: string; width?: string; workflow?: string; trigger?: string; autoTrigger?: boolean; query?: Record<string, unknown>; inputSchema?: Record<string, unknown> }>;
+      workflow?: string;
+      trigger?: string;
+      autoTrigger?: boolean;
+      query?: Record<string, unknown>;
+    }
+  >;
+  /** TEMPLATES (STATE_MODEL v2 §5 rules 3+5): the DECLARED STATE ORDER — the priority
+   *  ladder and arrival-scan order, from the manifest's `stateOrder`. First entry
+   *  outranks all below it; no name is special. Absent → legacy recency semantics. */
+  stateOrder?: string[];
+  /** THE LATCH, PER STATE (MCP guide §The Component Latch, moved here from the manifest
+   *  2026-08-31): the states whose wearer the conversation may be ADDRESSED AT, keyed by
+   *  state name. Compiled from each state's own `latch:` block and stamped beside
+   *  `stateOrder`, because states themselves are compiled away into `layouts`.
+   *
+   *  A state absent from this map can never hold the latch, so the SAME instance
+   *  retracted from its page state to an inline one drops the pill by construction —
+   *  which is the thing a manifest-level declaration could not say. `resolveLatch` reads
+   *  this map; nothing about the latch travels on the wire with a render. */
+  latches?: Record<string, { title: string; icon?: string }>;
+  /** COMPONENTS (STATE_MODEL v2 §5 rule 2): the PUBLIC MENU — the top-level state
+   *  names of the authored `state.view` tree, compiled at serve time. What hosts may
+   *  place at spawn and templates may react to; nested substates never appear here. */
+  publicStates?: string[];
+  /** REFERENCE, DON'T COPY: the shared pieces this definition NAMES rather than carries,
+   *  by ref name. Present only on the referenced form (`referencedDefinition`), which a
+   *  client asks for explicitly; the default form still inlines every Ref. */
+  defs?: Record<string, unknown>;
+  /** COMPONENTS (STATE_MODEL v2): the view tree's declared initial — the base the
+   *  client retracts to and the fallback when no host placement matches. */
+  initialView?: string;
+  /** COMPONENTS (STATE_MODEL v2): the authored `state.view` TREE, served as a nested
+   *  projection so viewers render states from the DECLARATION instead of scanning
+   *  layouts for Switches (the scan surfaced embedded components' content selectors —
+   *  a Document's tab cases — as fake states). Public states in tree order, each with
+   *  its layout, its substep discriminant (`on` + `initial`), and its private
+   *  substates. The tree stays the single source of truth; this is its projection. */
+  stateTree?: {
+    name: string;
+    layout?: string;
+    on?: string;
+    initial?: string;
+    states?: { name: string; layout?: string }[];
+  }[];
+}
+
+/** A COMPONENT manifest — `rx/components/<name>/manifest.json`. OPTIONAL: its PRESENCE
+ *  is what makes a component spatial-capable (a basic component has none and is never
+ *  discovered). It is the single home for the discovery meta; there is NO flag inside —
+ *  presence is the capability, the workbench registry toggle is the activation. */
+export interface ComponentManifest {
+  title?: string;
+  /** Display icon URL (square; shown in catalogs/drawers — never embedded). */
+  icon?: string;
+  description?: string;
+  /** Spatial-discovery selection text — see UnoverseDefinition.whenToUse. Required
+   *  in practice (the discoverability guard enforces it). */
+  whenToUse?: string;
+  category?: string;
+  version?: string;
+  /** The component's ARRIVAL state — an OPEN name (default "inline"). Injected into the
+   *  composed def's `state` block so the SDK renders that face on arrival; the component
+   *  still writes its own `defaultState` at runtime via setValue (STATE_MODEL §5b). This is
+   *  the render contract's home for the default state — parallel to a template's manifest. */
+  defaultState?: string;
+  /** LIFECYCLE opt-in — the phases whose server-side handler this component brings
+   *  (e.g. ["onStart"]). Each name maps to a sibling file (onStart → onstart.js), run by
+   *  the MCP render path. Presence here AUTHORIZES execution; a file with no opt-in is
+   *  inert. See UNOVERSE_AUTHORING.md §3c. */
+  lifecycle?: string[];
+}
+
+
+/** THE BASE ARRANGEMENT (UNOVERSE_TEMPLATE_MODEL §12): which layout is the app's
+ *  default. An explicit `layout:` still wins, but the line is no longer required —
+ *  states own layouts and declaration order ranks them, so the FIRST DECLARED STATE
+ *  is the base. "main" remains the default only for manifests with no states block. */
+export function defaultLayoutOf(m: { layout?: string; states?: unknown } | null | undefined): string {
+  if (typeof m?.layout === "string" && m.layout) return m.layout;
+  const states = m?.states;
+  if (states && typeof states === "object" && !Array.isArray(states)) {
+    const first = Object.keys(states)[0];
+    if (first) return first;
+  }
+  return "main";
+}
+
+/** THE DECLARATION WORD IS `type:` (authored; `kind:` is the legacy spelling, still
+ *  read). The catalogue filter matches on the internal `kind` field, so an envelope
+ *  written with the new word must land there — and the authored declaration is then
+ *  removed so a definition object never carries a stray top-level `type`. */
+export function normalizeDeclaredKind(d: UnoverseDefinition & { type?: unknown }): void {
+  const declared = d.type;
+  if (declared === "component" || declared === "template" || declared === "atom" || declared === "app") {
+    if (!d.kind) d.kind = declared;
+    delete d.type;
+  }
+}
+