@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/configs/CanvasConfig.js

@@ -0,0 +1,332 @@
+import { AI_LANES } from "../ai-lanes.js";
+import { defineEntity } from "../framework/defineEntity.js";
+import { Package } from "../entities/system/Package.js";
+import { Component } from "../entities/system/Component.js";
+import { Device } from "../entities/system/Device.js";
+import { Icon } from "../entities/system/Icon.js";
+import { Operation } from "../entities/system/Operation.js";
+import { Tool } from "../entities/system/Tool.js";
+import { defineConfig } from "../framework/defineConfig.js";
+import { System } from "./system.js";
+import { z } from "zod";
+//#region src/configs/CanvasConfig.ts
+/**
+* The canvas config — a design file as its own config TYPE, and every entity it owns, co-located in
+* one home (the same shape `../design-file.ts` keeps, which this supersedes).
+*
+* `Node` is the ONE kind, flat: every element is its own node row. A PLACED node — the thing
+* react-flow wraps — additionally carries `page` + geometry; its subtree nodes carry none and nest
+* under its id (`n1/badge` is part of `n1`, the same occupied-prefix containment `Card/Header`
+* uses), with `children`/`slots` as real node refs. Flat rather than an embedded keyed tree
+* because an embedded tree is the old `spec` jsonb blob again: one Yjs key per node means two
+* people editing different subtree elements conflict as whole-blob writes, and every edit re-ships
+* the tree. One row per element is the collaboration and write granularity. An instance is one
+* placed node, a generation placeholder is a placed node with no `type` yet.
+*
+* AI provenance is the chain node → `AiGeneration` → `AiFlow` → `AiMessage` → `AiChat`, every hop a
+* real ref. The system arrives WHOLE through `SystemSource` — never `LinkedSystem`'s partial-borrow
+* apparatus, which a canvas has no use for. See `docs/config-v2-spec-renderer-model.md`, "Where an
+* entity-shaped Spec lives".
+*
+* Lives in config-v2 (not studio) so every consumer can hold one: the derived `operation`/`tool`
+* catalog means the compact agent tools serve canvas CRUD the same way they serve the system's —
+* the MCP/CLI surface derives from the config type, and a studio-only home would fence
+* that off. Studio keeps the runtime halves (row mapping, Yjs session, dynamic registry), which
+* genuinely are app concerns.
+*/
+/**
+* `SystemSource` — this canvas's pointer at the ONE system it belongs to, in full. `LinkedSystem` is
+* the wrong mechanism here: it exists for a design system partially borrowing PIECES of another
+* (`link`, per-entity `options`, override/extend), and a canvas never does that — a node's `type`
+* always resolves against the whole of exactly one system.
+*
+* The source is attached under the system config's own `name`, which is `system-config` for a web
+* system and `react-native-system` for a native one, so a node ref the canvas mints
+* (`component:actions/Button@system-config`) means "the attached system". The system itself resolves
+* that ref as its own, through `Config.configFor`'s own-name rule.
+*/
+const SystemSource = defineEntity({
+	kind: "system-source",
+	fields: z.object({ 
+	/** Which system this is, for display and identity-change detection — not resolution itself,
+	*  which happens through `registerSources`/`Config.load` the same way every source kind works. */
+systemId: z.string().optional() }),
+	sourceIdentity: ["systemId"],
+	sourceResolution: {
+		resolved: z.object({ systemId: z.string().optional() }),
+		unavailable: z.object({
+			code: z.literal("not-found"),
+			systemId: z.string().optional()
+		})
+	},
+	linkable: false
+});
+/**
+* `Canvas` — a surface in a design file (a design file has one or more). Pages belong to a canvas,
+* nodes belong to a page (flat, ref-related, matching the real tables' `canvasId`/`pageId` columns).
+*/
+const Canvas = defineEntity({
+	kind: "canvas",
+	fields: z.object({ name: z.string().optional() })
+});
+/**
+* `Page` — a page within a `Canvas`. Field-for-field the `canvas_pages` table (id → path,
+* `canvasId` → the ref, timestamps DB-owned).
+*/
+const Page = defineEntity({
+	kind: "page",
+	fields: z.object({
+		canvas: Canvas,
+		name: z.string().optional(),
+		/** The page's URL segment — unique per canvas, the DB's `url_key`. */
+		urlKey: z.string().optional(),
+		/** No zod default — it would re-apply on any update that omits the field (see `Node.x`). */
+		sortOrder: z.number().optional()
+	})
+});
+/**
+* `AiChat` — one conversation. Deliberately minimal: the transcript is the `AiMessage` rows that
+* ref it (flat rows pointing at their owner, never an embedded array nothing can ref into).
+*/
+const AiChat = defineEntity({
+	kind: "ai-chat",
+	fields: z.object({ title: z.string().optional() }),
+	label: "AI chat",
+	linkable: false
+});
+/** `AiMessage` — one turn in an `AiChat`. */
+const AiMessage = defineEntity({
+	kind: "ai-message",
+	fields: z.object({
+		chat: AiChat,
+		role: z.enum(["user", "assistant"]),
+		content: z.string(),
+		/** Which model produced this turn — assistant messages only; a user turn has none. Per message
+		*  rather than per chat, because a conversation can switch models between turns. */
+		modelId: z.string().optional(),
+		/** Epoch ms — ordering within the chat. */
+		sentAt: z.number().optional()
+	}),
+	label: "AI message",
+	linkable: false
+});
+/**
+* `AiFlow` — the invocation that produced one or more generations: which surface it started from,
+* which model ran, how the agents were arranged, and — when it began as a chat turn — the message
+* that kicked it off. One flow can produce several nodes (a fanout literally does), so it is its
+* own entity rather than columns repeated per node.
+*/
+const aiFlowOrigin = z.enum([
+	"chat",
+	"comment",
+	"sidebar",
+	"paste",
+	"figma-paste",
+	"duplicate",
+	"mcp"
+]);
+const aiMultiAgentMode = z.enum([
+	"single",
+	"huddle",
+	"fanout"
+]);
+const AiFlow = defineEntity({
+	kind: "ai-flow",
+	fields: z.object({
+		origin: aiFlowOrigin,
+		lane: z.enum(AI_LANES).optional(),
+		modelId: z.string().optional(),
+		multiAgentMode: aiMultiAgentMode.optional(),
+		agentCount: z.number().optional(),
+		agentNames: z.array(z.string()).optional(),
+		/** The chat turn this flow answered, when `origin` is a conversation surface. */
+		message: AiMessage.optional()
+	}),
+	label: "AI flow",
+	linkable: false
+});
+/**
+* `AiGeneration` — how one node came to exist: the flow that produced it, and — for an iteration —
+* the lineage it varied from, as a real graph edge. Replaces the `canvas_nodes` table's
+* `generation_*` and `iteration_meta` columns, which all describe this one event.
+*/
+const AiGeneration = defineEntity({
+	kind: "ai-generation",
+	fields: z.object({
+		flow: AiFlow.optional(),
+		/** Iteration lineage — the node this generation varied from. Spelled as the ref shape rather
+		*  than the `Node` entity class, which is defined below this and would be a forward cycle. */
+		parentNode: z.object({ __ref: z.string().startsWith("node:") }).optional(),
+		iterationNumber: z.number().optional(),
+		description: z.string().optional(),
+		instructions: z.string().optional(),
+		generatedAt: z.number().optional()
+	}),
+	label: "AI generation",
+	linkable: false
+});
+/**
+* What a node or subtree element renders — a union of the kinds a spec `type` may name, each typed
+* by its own entity class (an entity class IS its kind's ref schema), never a bare string. Two arms
+* have no entity behind them yet, so the ref spells the grammar alone:
+*
+*  - `html:` — an intrinsic tag (`html:div`); a real kind is deferred (design doc, Platform).
+*  - `spec:` — the spec format's own renderer primitives, `spec:Slot` (a content hole — the
+*    placeholder a slot-fill drop creates, `shown` as a plain prop) and `spec:Fragment`. These are
+*    json-render/UDS-renderer supplied (`wrapRegistry` seeds both), never a system's vocabulary.
+*
+* json-render's remaining `UIElement` surface (`on`/`repeat`/`watch`) is deliberately absent — the
+* data-binding extension the design doc scopes as not started.
+*/
+const elementType = z.union([
+	Component,
+	Icon,
+	Package,
+	z.object({ __ref: z.string().startsWith("html:") }),
+	z.object({ __ref: z.enum(["spec:Slot", "spec:Fragment"]) })
+]);
+/** A ref to another node. `z.lazy` because `Node` is a SELF-reference — it isn't defined until the
+*  `defineEntity` call below returns, and the explicit annotation breaks the circular type
+*  inference (same pattern `Token`'s self-referencing value uses). */
+const nodeRef = z.lazy(() => Node);
+/** A placed node's frame size — freeform, or powered by a system device. */
+const Size = z.discriminatedUnion("type", [z.object({
+	type: z.literal("custom"),
+	width: z.number(),
+	height: z.number()
+}), z.object({
+	type: z.literal("device"),
+	ref: Device
+})]);
+/**
+* `Node` — the unit of a canvas: one element, one record, one row. FLAT — a subtree node is its own
+* item nested under its placed root's id (`n1/badge`), and `children`/`slots` hold real node refs,
+* so `dependents()`, delete-refusal and rename-cascade come from the framework instead of
+* `reKeySlotRefs` (UDS-3526) / `gcUnreachableElements` (UDS-3557) hand-rolling them per gesture.
+*
+* Placement fields are present on a PLACED node (`page` is the discriminant — what the canvas lists
+* and react-flow wraps) and absent on subtree nodes. `type` is optional for exactly one reason: a
+* placed node awaiting its first generation (today's skeleton / pending placeholder) exists before
+* anyone knows what it renders.
+*/
+const Node = defineEntity({
+	kind: "node",
+	fields: z.object({
+		/** A real ref, never a bare name — dependents()/rename-cascade need a real edge, and a bare
+		*  `kind:path` string the framework never walks gives neither. Absent only on a placeholder
+		*  awaiting generation. */
+		type: elementType.optional(),
+		props: z.record(z.string(), z.unknown()).optional(),
+		/** The default slot's fill — refs to this node's subtree nodes. */
+		children: z.array(nodeRef).describe("Refs to this node's subtree nodes. A child's path nests under this node's root path, such as \"card/title\" under \"card\".").optional(),
+		/** Named slots — never folded into `props`; see symptom 5 in the design doc for why. */
+		slots: z.record(z.string(), z.array(nodeRef)).describe("Named slot fills, each a list of refs to this node's subtree nodes. A fill's path nests under this node's root path, such as \"card/footer-badge\" under \"card\".").optional(),
+		/** json-render's own visibility grammar, borrowed rather than reinvented. */
+		visible: z.unknown().optional(),
+		/** json-render's repeat grammar — carried opaquely; the data-binding extension the design doc
+		*  scopes as not started would give its refs real edges. */
+		repeat: z.unknown().optional(),
+		/** An element-level linked reference (studio's `ElementRef`): this element follows an element
+		*  of another node, diverging only by its overrides. Opaque here — its `sourceId`/`sourceKey`
+		*  are resolved by the canvas's linked-copy machinery, not the ref graph; modeling them as real
+		*  refs is an open follow-up. */
+		ref: z.unknown().optional(),
+		/** The layers rail's lock on this element: the canvas stops hit-testing it and everything
+		*  beneath it, while the rail can still select it to unlock. */
+		locked: z.boolean().optional(),
+		/** The element's name in the layers rail. On a placed node it is the node's own name, which the
+		*  rename gesture writes and a spec write leaves alone; on a subtree node it travels with the
+		*  element. */
+		label: z.string().optional(),
+		page: Page.optional(),
+		/** The placed node this one nests inside on the CANVAS (react-flow parent/grouping) — a
+		*  different relation from `children`, which is render containment. */
+		parent: nodeRef.optional(),
+		size: Size.optional(),
+		x: z.number().optional(),
+		y: z.number().optional(),
+		collapsed: z.boolean().optional(),
+		/** Stacking rank among the page's frames (the legacy `spec.order`). Placed nodes only. */
+		order: z.number().optional(),
+		/** A node-level linked-copy descriptor (studio's `LinkedSource`): this node renders another
+		*  node's subtree with overrides. Opaque, same reasoning as `ref`. */
+		linkedSource: z.unknown().optional(),
+		/** The spec's state model (`spec.state`) — the data-binding surface, carried opaquely until
+		*  config-v2 models state paths. Placed nodes only. */
+		state: z.record(z.string(), z.unknown()).optional(),
+		/** The spec's own `meta` bag. Placed nodes only. */
+		meta: z.record(z.string(), z.unknown()).optional(),
+		/** How this node came to exist, when AI produced it. */
+		generation: AiGeneration.optional(),
+		/** The placed node this one was duplicated from, when it lives on the same canvas. */
+		duplicatedFrom: nodeRef.optional()
+	}),
+	computed: { 
+	/**
+	* What a layers rail (or any listing) calls this node: its authored
+	* `label`, else what its `type` names — the component's own display label,
+	* resolved through the same path everything else resolves refs by, so a
+	* `kind:` marker never reaches a person. A placeholder awaiting generation
+	* (no `type` yet) and a linked copy (a descriptor, no `type` of its own)
+	* have no name here; the surface falls back to what it can resolve.
+	*
+	* The read type intersects this with the base `Entity.displayLabel`, which
+	* is never `undefined`, so the intersection reads as `string`. The canvas
+	* node view re-types the field optional at its seam.
+	*/
+displayLabel: ({ member, config }) => {
+		const label = member.label;
+		if (typeof label === "string" && label.trim().length > 0) return label;
+		if (member.linkedSource != null) return void 0;
+		const type = member.type;
+		return type ? config.displayLabelOf(type) : void 0;
+	} }
+});
+/**
+* `CanvasConfig` — the design-file config TYPE. Owns placement, content, and AI provenance (flat,
+* ref-related), DRAWS ON a system, and derives the same agent-tool catalog (`operation`/`tool`) as
+* the system so its design-file CRUD tools project from it.
+*
+* A source, not a read-through window onto every one of the system's kinds. A node's `type` carries
+* the source it points into (`component:actions/Button@<slug>`), so one resolution path serves both
+* and nothing has to know that THIS config borrows a whole kind. Read-only stays read-only: a
+* source's items resolve through their own config, so there is no local collection to offer CRUD
+* over.
+*/
+const CanvasConfig = defineConfig({
+	name: "canvas",
+	entities: {
+		canvases: Canvas,
+		pages: Page,
+		nodes: Node,
+		chats: AiChat,
+		messages: AiMessage,
+		flows: AiFlow,
+		generations: AiGeneration,
+		systems: SystemSource
+	},
+	sources: { systems: () => System },
+	derivedEntities: {
+		operations: Operation,
+		tools: Tool
+	}
+});
+/**
+* Build a plain (in-memory) canvas target: borrows the system read-only, under its own `name` as the
+* slug, and seeds the canvas + page it starts with. Enough to project tools or run an eval; the
+* live form is the studio session (`apps/studio/src/configs/canvas/canvas-session.ts`).
+*/
+function createCanvasConfig(system) {
+	return new CanvasConfig().register({
+		canvases: { main: {} },
+		pages: { home: { canvas: Canvas.ref("main") } },
+		nodes: {},
+		chats: {},
+		messages: {},
+		flows: {},
+		generations: {},
+		systems: { [system.name]: {} }
+	}).registerSources({ systems: { [system.name]: system } });
+}
+//#endregion
+export { AiChat, AiFlow, AiGeneration, AiMessage, Canvas, CanvasConfig, Node, Page, SystemSource, createCanvasConfig };

package/dist/configs/build-options.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+//#region src/configs/build-options.d.ts
+/** The section as a config that set nothing reads it, spelled once. */
+declare const BUILD_DEFAULTS: {
+  readonly outDir: ".uds";
+  readonly registryDir: ".uds-registry";
+};
+//#endregion
+export { BUILD_DEFAULTS };

package/dist/configs/build-options.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+//#region src/configs/build-options.ts
+/**
+* The `build` section's fields — where a repo keeps a system's sources, where the build writes, and
+* where linked systems are materialised. Shared by the web and the native config type.
+*
+* Every field is optional and none carries a schema default. A stored body is exactly what was
+* authored, so a default that changes later reaches every system that never set the field. The
+* defaults live in {@link BUILD_DEFAULTS}, which the directory resolvers read.
+*/
+/**
+* A directory INSIDE the project, refused at the point it is written.
+*
+* `outDir` is handed to `rmSync(dir, { recursive: true })` before every build, because a build
+* cleans its own output. So a value that names the project root deletes the project, and one with a
+* `..` in it deletes whatever is up there — from a field in a checked-in config file, which is a very
+* different exposure from a `--output-dir` somebody typed.
+*
+* Refused here rather than at the delete, so a config carrying one never loads at all and the message
+* names the field. The build keeps a second check anyway: this schema only sees a config that came
+* through it, and an artifact can arrive from elsewhere.
+*/
+const insideProject = (field) => z.string().min(1).refine((value) => !value.startsWith("/") && !/^[A-Za-z]:/.test(value), { message: `\`${field}\` has to be relative to the config, not an absolute path.` }).refine((value) => {
+	const segments = value.replace(/\\/g, "/").split("/").filter((part) => part !== "");
+	return segments.length > 0 && !segments.every((part) => part === ".") && !segments.includes("..");
+}, { message: `\`${field}\` has to name a directory inside the project — not \`.\`, and not one that climbs out with \`..\`.` });
+/** The section as a config that set nothing reads it, spelled once. */
+const BUILD_DEFAULTS = {
+	outDir: ".uds",
+	registryDir: ".uds-registry"
+};
+const buildFields = z.strictObject({
+	/**
+	* The directory every file this system seals must live under, relative to the config.
+	*
+	* Declared rather than inferred. Without it the boundary is guessed per file from the
+	* conventional `uds/components/` anchor, and a component that reaches a helper beside it —
+	* `../../shared/tone` from `src/uds/components`, an ordinary app layout — climbs out of a root
+	* nobody chose and cannot be mirrored into the output at all.
+	*
+	* Setting it also fixes the emitted layout: a module and the files it imports are both written
+	* relative to THIS directory, so the tree beneath it survives the move into {@link outDir} and a
+	* relative specifier still resolves. That is what makes reaching outside it the real error, rather
+	* than a guess about where the components root probably was.
+	*
+	* No default, and that is the answer rather than a missing one: unset, the anchor convention stands
+	* and the output layout is unchanged.
+	*/
+	inputDir: insideProject("inputDir").meta({
+		title: "Input directory",
+		description: "The directory every sealed component file lives under, relative to the config. Emitted modules keep the layout beneath it. Unset, the `uds/components/` folder convention applies."
+	}).optional(),
+	/** Where `uds build` writes. A CLI `--output-dir` still wins, because a one-off build into a
+	*  scratch directory is not a property of the system. */
+	outDir: insideProject("outDir").meta({
+		title: "Output directory",
+		description: `Where \`uds build\` writes, relative to the config. The build cleans it before writing, so it has to stay inside the project. Unset, \`${BUILD_DEFAULTS.outDir}\`.`,
+		default: BUILD_DEFAULTS.outDir
+	}).optional(),
+	/** Where `uds pull` materializes linked-system sources — see `resolveRegistryDir`. */
+	registryDir: z.string().min(1).meta({
+		title: "Registry directory",
+		description: `Where \`uds pull\` places the sources of linked systems, relative to the config. Unset, \`${BUILD_DEFAULTS.registryDir}\`.`,
+		default: BUILD_DEFAULTS.registryDir
+	}).optional()
+});
+//#endregion
+export { BUILD_DEFAULTS, buildFields };

package/dist/configs/platform.d.ts

@@ -0,0 +1,15 @@
+import { Config } from "../framework/Config.js";
+import { ReactNativeSystemConfig } from "./react-native-system.js";
+import { SystemConfig } from "./system.js";
+
+//#region src/configs/platform.d.ts
+/**
+ * A design system of either platform — what a holder declares when it draws on a system and has no
+ * reason to care which platform it is: the canvas, a session, a pipeline step.
+ */
+type AnySystemConfig = SystemConfig | ReactNativeSystemConfig;
+declare function isNativeConfig(config: Config): boolean;
+/** Whether a config is a design system at all, of either platform. A canvas config is not. */
+declare function isSystemConfig(config: Config): config is AnySystemConfig;
+//#endregion
+export { AnySystemConfig, isNativeConfig, isSystemConfig };

package/dist/configs/platform.js

@@ -0,0 +1,17 @@
+//#region src/configs/platform.ts
+/**
+* The names `System` and `ReactNativeSystem` declare themselves under. Held here rather than read
+* off the classes so this module imports nothing at runtime: an entity module can ask which platform
+* a config is without pulling in the config type that registers it, which would close an import cycle.
+*/
+const WEB_CONFIG_NAME = "system-config";
+const NATIVE_CONFIG_NAME = "react-native-system";
+function isNativeConfig(config) {
+	return config.name === NATIVE_CONFIG_NAME;
+}
+/** Whether a config is a design system at all, of either platform. A canvas config is not. */
+function isSystemConfig(config) {
+	return config.name === "system-config" || config.name === "react-native-system";
+}
+//#endregion
+export { NATIVE_CONFIG_NAME, WEB_CONFIG_NAME, isNativeConfig, isSystemConfig };