@texuli/spec 0.1.0-next.0 → 0.1.0-next.3

package/README.md

@@ -1,98 +1,168 @@
 # @texuli/spec
 
-The schema-first blueprint contract (spec/Compose design, plan B1): the
-platform-neutral source of truth for blueprint structure, the catalog
-vocabulary, capability tiers and diagnostics. TypeScript and Kotlin are
-deterministic projections generated from it, and a conformance harness keeps
-everything from drifting.
-
-**Status: in development, not published.** Layer 0, no dependencies,
-framework-free. Kotlin is generated as committed text by this package's
-TypeScript generator; no Kotlin toolchain runs here, and nothing is compiled
-or published to Maven.
-
-## Layout
-
-| Path | What it holds |
-| --- | --- |
-| `schemas/` | The normative JSON schemas: `blueprint` (envelope v1 and the node tree), `catalog`, `diagnostics`, `manifest` |
-| `catalog/components.json` | The closed vocabulary, projected from the built catalog: id, label, summary, group, placement (`app`/`content`), emit tiers, capability and props |
-| `catalog/capabilities.json` | Reviewed capability claims. Empty: no id is audited portable yet, so every capability is `unknown` (ADR-003) |
-| `fixtures/golden/` | Blueprints that must validate: a report, a dashboard and a proactive deck (fictional data) |
-| `fixtures/invalid/` | Blueprints that must fail with exact diagnostic codes, one or more per code |
-| `manifest.json` | The spec version, the dialect and a SHA-256 per normative file |
-| `generated/typescript/`, `generated/kotlin/` | The projections. Never edit them |
-| `generated-manifest.json` | A SHA-256 per generated file |
-
-## The dialect
-
-Schemas use a closed subset of JSON Schema 2020-12 (`DIALECT_KEYWORDS`):
-`type`, `properties`, `required`, `additionalProperties`, `items`, `enum`,
-`const`, string, number and array bounds, `pattern`, and local `$ref` /
-`$defs`. Objects must be closed (`additionalProperties: false`) or explicit
-maps. Anything else fails `checkSchemaDocument`, and generation refuses it.
-
-## Exports
-
-- `@texuli/spec`, the runtime half:
-  - the generated types (`BlueprintEnvelope`, `SpecCatalog`, `SpecValidation` …);
-  - `SPEC_COMPONENT_IDS` and `SpecComponentProps`;
-  - `validateInstance` (the dialect validator);
-  - `validateBlueprint` (the target-neutral blueprint check: envelope
-    schema, closed ids and props, prop kinds and enums, required props, no
-    platform-extension props from data, the portable profile failing closed,
-    and an optional catalog binding);
-  - `canonicalJson` and a synchronous `sha256`.
-- `@texuli/spec/codegen`, build time: `buildSpec`, `projectCatalog`,
-  `checkConformance`, `formatJson`.
-
-URL policy, tree limits, grammar and rendering stay in the runtime validator,
-`@texuli/catalog/validate`.
-
-## Projections
-
-- **Web extensions.** Props of kind `slot`, `event` or `unknown`, and the
-  `class`, `className`, `style` and chart `renderer` props, are marked
-  `extension: "web"`. They are left out of `SpecComponentProps`, and data
-  that sets them is refused.
-- **Kotlin** (`com.texuli.spec`, Kotlin 1.9+ for `entries` and
-  `data object`): data classes, closed enums and static decoders over a
-  generated `JsonValue` model, with no library dependency. Decoders check
-  JSON types, required and unknown fields, enums and constants. Patterns
-  and limits are the shared validator's job.
-- **Stamp.** Every generated file carries the spec version and a digest of
-  the normative files. There are no timestamps, and output is
-  byte-identical for the same inputs in any order.
-
-## Regenerate
+The blueprint contract of [Texuli](https://texuli.com), an MIT-licensed
+Svelte 5 component library by Dailybot, Inc. (*Small pieces. Infinite
+possibilities.*). A **blueprint** is a JSON document, usually written by an
+AI agent, that describes an interface as a tree of components from Texuli's
+closed catalog. `@texuli/spec` is the platform-neutral source of truth for
+that format: the generated TypeScript types, the closed component
+vocabulary, a target-neutral blueprint validator and deterministic hashing.
+
+Use it when you generate, store, diff or check blueprints, or build a
+renderer for them. The same contract also generates the Kotlin models used
+by Texuli's Kotlin Multiplatform twin. The package is framework-free: no
+DOM, no Svelte, no Node APIs and no runtime dependencies.
+
+> **Status: preview.** Texuli is in development. The packages are published
+> to npm as prereleases under the `next` dist-tag, and there is no stable
+> release yet, so install with `@next`. APIs may still change between
+> previews.
+
+## Install
 
 ```bash
-pnpm exec tsx packages/spec/scripts/bootstrap-catalog.ts   # refresh catalog/components.json from the built catalog
-pnpm exec tsx packages/spec/scripts/generate.ts            # write manifests and projections
-pnpm exec tsx packages/spec/scripts/generate.ts --check    # fail on drift
+npm install @texuli/spec@next
 ```
 
-## Conformance
-
-`pnpm vitest run packages/spec` runs the harness. Drift is a failed gate:
-- every schema stays in the dialect;
-- the manifest digests match the normative files;
-- regenerating gives byte-identical files, none missing or extra;
-- the golden fixtures validate and the invalid fixtures fail with exactly
-  their codes, covering every diagnostic code;
-- `components.json` equals the projection of the live catalog, and the
-  blueprint schema matches the envelope `@texuli/catalog` reads;
-- generation is deterministic and refuses schemas outside the dialect;
-- the Kotlin text declares its package, balances its brackets, defines
-  every type it references and decodes closed.
-
-When the catalog changes, refresh `components.json`, regenerate and review
-the diff.
-
-## Not yet
-
-- Behavior contracts, token roles and the token-to-Compose generator (B1
-  steps 2 and 5).
-- Making the spec authoritative for the web packages (B1 step 3 cutover);
-  today the catalog manifests are the bootstrap input.
-- Compiling the Kotlin, and the native runtime (B2).
+```bash
+pnpm add @texuli/spec@next
+# or
+yarn add @texuli/spec@next
+```
+
+No peer dependencies and no CSS. The package is ESM-only and ships
+TypeScript declarations. The normative JSON documents (the blueprint
+schema, the component catalog and the fixtures) live in the
+[repository](https://github.com/DailybotHQ/texuli/tree/main/packages/spec);
+they are not part of the npm package.
+
+## Quick start
+
+```ts
+import {
+  canonicalJson,
+  type Schema,
+  SPEC_COMPONENT_IDS,
+  SPEC_VERSION,
+  sha256,
+  validateInstance,
+} from '@texuli/spec';
+
+SPEC_VERSION;                         // the spec version, e.g. '0.2.0'
+SPEC_COMPONENT_IDS.includes('alert'); // true: the closed component vocabulary
+
+// The dialect validator: a closed subset of JSON Schema 2020-12.
+const schema: Schema = {
+  type: 'object',
+  properties: { title: { type: 'string', maxLength: 80 } },
+  required: ['title'],
+  additionalProperties: false,
+};
+validateInstance(schema, { title: 'Weekly report' }); // []
+validateInstance(schema, { title: 42, extra: true });
+// [{ code: 'type', path: '$.title', … }, { code: 'additional-property', path: '$.extra', … }]
+
+// Deterministic serialization and hashing, identical in every runtime.
+const digest = sha256(canonicalJson({ b: 1, a: [true, null] }));
+```
+
+To check a whole blueprint, pass the blueprint schema and catalog documents
+from the repository's `packages/spec/schemas/blueprint.schema.json` and
+`packages/spec/catalog/components.json`:
+
+```ts
+import { type Schema, type SpecCatalog, validateBlueprint } from '@texuli/spec';
+
+const result = validateBlueprint(blueprint, {
+  blueprintSchema: blueprintSchemaJson as Schema,
+  catalog: componentsJson as SpecCatalog,
+});
+if (!result.ok) {
+  for (const d of result.diagnostics) console.warn(d.code, d.path, d.message);
+}
+```
+
+A node with an id outside the catalog fails with `unknown-id`; other codes
+include `schema`, `unknown-prop`, `prop-type`, `enum-value`,
+`missing-required`, `extension-prop`, `catalog-mismatch`,
+`unsupported-profile` and `unknown-slot`.
+
+## What's inside
+
+| Subpath | Purpose | Headline exports |
+| --- | --- | --- |
+| `@texuli/spec` | Runtime: types, vocabulary, validation, hashing | `BlueprintEnvelope`, `SpecCatalog`, `SpecValidation` and the other generated types; `SPEC_COMPONENT_IDS`, `SpecComponentProps`, `SPEC_CATALOG_HASH`, `SPEC_VERSION`; `validateBlueprint`, `validateTree`, `validateInstance`, `checkSchemaDocument`; `canonicalJson`, `sha256` |
+| `@texuli/spec/codegen` | Build time: generation and conformance | `buildSpec`, `projectCatalog`, `checkConformance`, `formatJson`, `nextSpecVersion`, `checkVersionHistory` |
+
+## Key guarantees
+
+- **Closed vocabulary.** Component ids, prop names, prop kinds and enum
+  values are closed; anything outside the catalog is refused.
+- **No platform props from data.** Web-only props (slots, events, `class`,
+  `className`, `style` and the chart `renderer`) are marked as web
+  extensions, left out of `SpecComponentProps`, and refused when a
+  blueprint sets them.
+- **Fails closed.** The portable profile is refused until a capability is
+  audited portable, and a blueprint bound to another catalog hash is
+  refused when you pass `catalogHash`.
+- **Deterministic.** Canonical JSON sorts keys at every depth, and every
+  generated file carries the spec version and digest with no timestamps.
+- **Structure only.** This validator checks structure. URL policy, tree
+  limits and rendering live in the runtime validator of
+  [`@texuli/catalog`](https://www.npmjs.com/package/@texuli/catalog).
+
+## Versioning
+
+The spec has its own semantic version (`SPEC_VERSION`), separate from the
+npm package version. The **spec digest** is the SHA-256 of the manifest
+that pins every normative file (schemas, catalog and fixtures); any
+normative change moves the digest and requires a new spec version.
+
+| Change class | Examples | Before 1.0.0 | From 1.0.0 |
+| --- | --- | --- | --- |
+| patch | Descriptions, diagnostic wording, a fixture for behavior that already holds | patch | patch |
+| minor | Optional fields, new catalog ids, new optional props, new diagnostic codes for data that was already refused | minor | minor |
+| major | Removing or renaming ids, props or fields; changing a prop type; making something required | minor | major |
+
+For TypeScript consumers, a patch leaves the generated types and
+`SPEC_COMPONENT_IDS` unchanged; code that compiled against a minor release
+keeps compiling, though new optional fields and ids can appear in data it
+reads. Native (Kotlin) builds compile the generated models from the same
+spec, and their decoders are closed: a blueprint that uses a field from a
+newer spec fails to decode on an older native build with a `schema`
+diagnostic instead of passing silently. A blueprint binds to an exact
+catalog hash today; an envelope field for a compatible spec range, and
+migrations between versions, are planned and not built.
+
+The full rules (the digest, `versions.json` pins, regeneration and the
+conformance harness) are in
+[contract.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/contract.md).
+
+## Documentation
+
+- Website: [texuli.com](https://texuli.com), the
+  [agents overview](https://texuli.com/agents-page/) and
+  [web and native](https://texuli.com/web-and-native/)
+- Schemas, catalog and fixtures:
+  [packages/spec](https://github.com/DailybotHQ/texuli/tree/main/packages/spec)
+- The contract in depth (the JSON Schema dialect, projections, conformance
+  and versioning): [contract.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/contract.md)
+- The Kotlin Multiplatform twin that consumes the generated models:
+  [native/README.md](https://github.com/DailybotHQ/texuli/blob/main/native/README.md)
+- Architecture: [ARCHITECTURE.md](https://github.com/DailybotHQ/texuli/blob/main/docs/ARCHITECTURE.md)
+
+## Related packages
+
+- [`@texuli/catalog`](https://www.npmjs.com/package/@texuli/catalog): the agent catalog and the renderer with no HTML sinks.
+- [`@texuli/player`](https://www.npmjs.com/package/@texuli/player): the Svelte paint runtime for validated blueprints.
+- [`texuli`](https://www.npmjs.com/package/texuli): the styled Svelte 5 components blueprints are built from.
+
+## Contributing
+
+Source, issues and contribution guidelines live at
+[github.com/DailybotHQ/texuli](https://github.com/DailybotHQ/texuli). Report
+bugs at [github.com/DailybotHQ/texuli/issues](https://github.com/DailybotHQ/texuli/issues).
+
+## License
+
+MIT © Dailybot, Inc.

package/dist/catalog.d.ts

@@ -3,7 +3,7 @@
  * projection from a built catalog. The projection is the bootstrap step of
  * spec/Compose design §2.3; the parity check reruns it to catch drift.
  */
-import type { SpecCatalog, SpecComponent, SpecProp } from '../generated/typescript/catalog-schema.js';
+import type { SpecCatalog, SpecComponent, SpecProp } from './generated/typescript/catalog-schema.js';
 export type { SpecCatalog, SpecComponent, SpecProp };
 export declare const CAPABILITIES: readonly ["portable-core", "web-only", "native-only", "unknown"];
 export type Capability = SpecComponent['capability'];

package/dist/codegen/index.d.ts

@@ -9,5 +9,6 @@ export { prettyJson } from '../canonical.js';
 export { type BuiltCatalogLike, projectCatalog } from '../catalog.js';
 export { type ConformanceIssue, checkConformance } from '../conformance.js';
 export { formatJson, LINE_WIDTH } from '../format.js';
+export { checkVersionHistory, nextSpecVersion, type SpecChangeClass, type SpecVersionHistory, type SpecVersionPin, type VersionIssue, } from '../versioning.js';
 export { KOTLIN_PACKAGE, kotlinString } from './kotlin.js';
 export type { SchemaUnit, Stamp } from './shared.js';

package/dist/codegen/index.js

@@ -9,4 +9,5 @@ export { prettyJson } from "../canonical.js";
 export { projectCatalog } from "../catalog.js";
 export { checkConformance } from "../conformance.js";
 export { formatJson, LINE_WIDTH } from "../format.js";
+export { checkVersionHistory, nextSpecVersion, } from "../versioning.js";
 export { KOTLIN_PACKAGE, kotlinString } from "./kotlin.js";

package/{generated → dist/generated}/typescript/blueprint.d.ts

@@ -47,13 +47,55 @@ export interface BlueprintEditOp {
     tree?: BlueprintNode;
 }
 export type BlueprintNodePath = readonly number[];
-/** One catalog node: id, props and children only. */
+/** One catalog node: id, props, children, and an optional named slot and condition. */
 export interface BlueprintNode {
     /** A catalog component id. */
     id: string;
     /** Props checked against the component's catalog entry. */
     props?: Readonly<Record<string, unknown>>;
     children?: readonly BlueprintNode[];
+    /**
+     * The parent's named slot this node fills (audit G04): a slot prop of the parent's catalog entry.
+     * Omitted or "children" is the default slot.
+     */
+    slot?: string;
+    when?: BlueprintCondition;
+}
+/**
+ * Shows the node when true (audit G07): the closed Condition AST of the blocks formula grammar.
+ * False or unknown hides the node. Structural shape only; which operands each op needs, and the
+ * size limits, are checked by the runtime formula parser.
+ */
+export interface BlueprintCondition {
+    op: 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'neq' | 'and' | 'or' | 'not';
+    left?: BlueprintNumberFormula;
+    right?: BlueprintNumberFormula;
+    /** The conditions of and / or. */
+    args?: readonly BlueprintCondition[];
+    value?: BlueprintCondition;
+}
+/**
+ * A number expression of the blocks formula grammar. Structural shape only; the runtime formula
+ * parser checks which operands each op needs.
+ */
+export interface BlueprintNumberFormula {
+    op: 'num' | 'var' | 'add' | 'sub' | 'mul' | 'div' | 'pow' | 'min' | 'max' | 'round' | 'clamp' | 'if';
+    /** A number for num; a number formula for round and clamp. */
+    value?: unknown;
+    /** The input a var reads. */
+    name?: string;
+    left?: BlueprintNumberFormula;
+    right?: BlueprintNumberFormula;
+    base?: BlueprintNumberFormula;
+    exponent?: BlueprintNumberFormula;
+    /** The operands of min / max. */
+    args?: readonly BlueprintNumberFormula[];
+    digits?: number;
+    min?: BlueprintNumberFormula;
+    max?: BlueprintNumberFormula;
+    test?: BlueprintCondition;
+    ifTrue?: BlueprintNumberFormula;
+    ifFalse?: BlueprintNumberFormula;
 }
 /**
  * Envelope version 1 around one catalog tree (ADR-003, audit G13). Mirrors what

package/{generated → dist/generated}/typescript/blueprint.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/blueprint.schema.json. Do not edit: run the spec generator.
-// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
 export {};

package/{generated → dist/generated}/typescript/catalog-schema.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/catalog.schema.json. Do not edit: run the spec generator.
-// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
 export {};

package/{generated → dist/generated}/typescript/diagnostics.d.ts

@@ -4,7 +4,7 @@ export interface SpecDiagnostic {
     message: string;
     id?: string;
 }
-export type SpecDiagnosticCode = 'schema' | 'unknown-id' | 'unknown-prop' | 'prop-type' | 'enum-value' | 'missing-required' | 'extension-prop' | 'catalog-mismatch' | 'unsupported-profile';
+export type SpecDiagnosticCode = 'schema' | 'unknown-id' | 'unknown-prop' | 'prop-type' | 'enum-value' | 'missing-required' | 'extension-prop' | 'catalog-mismatch' | 'unsupported-profile' | 'unknown-slot';
 /** The stable result shape of validating a blueprint against the spec. */
 export interface SpecValidation {
     ok: boolean;

package/{generated → dist/generated}/typescript/diagnostics.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/diagnostics.schema.json. Do not edit: run the spec generator.
-// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
 export {};

package/{generated → dist/generated}/typescript/manifest.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/manifest.schema.json. Do not edit: run the spec generator.
-// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
 export {};

package/{generated → dist/generated}/typescript/vocabulary.d.ts

@@ -1,7 +1,7 @@
 /** The built catalog this vocabulary was projected from. */
-export declare const SPEC_CATALOG_HASH = "2516510c15ec62a630d56770349e47cad35f6d0e1654e8116ab1ef2607572617";
+export declare const SPEC_CATALOG_HASH = "b073e30b4c8b1a30b3ef3ccb372e552d2d88e584616b74591c6c32923b471376";
 /** Every closed component id, sorted. */
-export declare const SPEC_COMPONENT_IDS: readonly ["alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "description", "detail-panel", "dialog", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "form", "hover-card", "hover-card-content", "icon-button", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-settings", "layout-sidebar", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "split-view", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "timeline", "toaster", "tooltip"];
+export declare const SPEC_COMPONENT_IDS: readonly ["alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "deck-slide", "description", "detail-panel", "dialog", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "form", "hover-card", "hover-card-content", "icon-button", "inline-text", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-settings", "layout-sidebar", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "split-view", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "timeline", "toaster", "tooltip"];
 export type SpecComponentId = (typeof SPEC_COMPONENT_IDS)[number];
 /** The props a blueprint may set on each component (platform extensions left out). */
 export interface SpecComponentProps {
@@ -44,6 +44,7 @@ export interface SpecComponentProps {
         variant?: 'default' | 'inset';
     };
     badge: {
+        label?: string;
         variant?: 'default' | 'secondary' | 'outline' | 'success' | 'warning' | 'destructive' | 'info' | 'neutral';
     };
     banner: {
@@ -112,6 +113,7 @@ export interface SpecComponentProps {
         disabled?: boolean;
         href?: string;
         hrefTrust?: 'developer' | 'untrusted';
+        label?: string;
         loading?: boolean;
         loadingLabel?: string;
         size?: 'sm' | 'md' | 'lg' | 'icon';
@@ -147,6 +149,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-bar': {
         annotations?: string;
@@ -156,6 +159,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-bubble': {
         annotations?: string;
@@ -170,6 +174,7 @@ export interface SpecComponentProps {
     };
     'charts-bullet': {
         description?: string;
+        format?: Readonly<Record<string, unknown>>;
         label: string;
         labels?: Readonly<Record<string, unknown>>;
         max?: number;
@@ -192,6 +197,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-combo': {
         annotations?: string;
@@ -201,6 +207,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-donut': {
         data: readonly unknown[];
@@ -223,6 +230,7 @@ export interface SpecComponentProps {
     'charts-gauge': {
         bandLabels?: readonly unknown[];
         description?: string;
+        format?: Readonly<Record<string, unknown>>;
         label: string;
         labels?: Readonly<Record<string, unknown>>;
         max?: number;
@@ -268,6 +276,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-network': {
         description?: string;
@@ -289,6 +298,7 @@ export interface SpecComponentProps {
     };
     'charts-progress-ring': {
         description?: string;
+        format?: Readonly<Record<string, unknown>>;
         label: string;
         labels?: Readonly<Record<string, unknown>>;
         max?: number;
@@ -318,6 +328,7 @@ export interface SpecComponentProps {
     };
     'charts-sparkline': {
         description?: string;
+        format?: Readonly<Record<string, unknown>>;
         height?: number;
         label: string;
         labels?: Readonly<Record<string, unknown>>;
@@ -334,6 +345,7 @@ export interface SpecComponentProps {
         mode?: 'light' | 'dark';
         series: readonly unknown[];
         title: string;
+        visibleDomain?: string;
     };
     'charts-sunburst': {
         description: string;
@@ -422,6 +434,13 @@ export interface SpecComponentProps {
     'context-menu-trigger': {
         disabled?: boolean;
     };
+    'deck-slide': {
+        master?: 'title' | 'section' | 'content' | 'two-column' | 'media-left' | 'media-right' | 'quote' | 'closing';
+        notes?: string;
+        slideId: string;
+        title?: string;
+        transition?: 'none' | 'fade' | 'fade-up';
+    };
     description: Record<string, never>;
     'detail-panel': {
         closeOnEscape?: boolean;
@@ -508,6 +527,9 @@ export interface SpecComponentProps {
         loading?: boolean;
         variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
     };
+    'inline-text': {
+        text: string;
+    };
     input: {
         clearLabel?: string;
         clearable?: boolean;
@@ -525,7 +547,9 @@ export interface SpecComponentProps {
         readonly?: boolean;
         value?: string;
     };
-    kbd: Record<string, never>;
+    kbd: {
+        label?: string;
+    };
     kpi: {
         comparisonLabel?: string;
         currency?: string;
@@ -576,6 +600,11 @@ export interface SpecComponentProps {
         storageKey?: string;
     };
     'layout-deck': {
+        aspect?: '16:9' | '4:3' | '1:1';
+        description?: string;
+        locale?: string;
+        masters?: readonly unknown[];
+        settings?: Readonly<Record<string, unknown>>;
         slides?: readonly unknown[];
         title?: string;
     };

package/{generated → dist/generated}/typescript/vocabulary.js

@@ -1,7 +1,7 @@
 // Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
-// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
 /** The built catalog this vocabulary was projected from. */
-export const SPEC_CATALOG_HASH = '2516510c15ec62a630d56770349e47cad35f6d0e1654e8116ab1ef2607572617';
+export const SPEC_CATALOG_HASH = 'b073e30b4c8b1a30b3ef3ccb372e552d2d88e584616b74591c6c32923b471376';
 /** Every closed component id, sorted. */
 export const SPEC_COMPONENT_IDS = [
     'alert',
@@ -55,6 +55,7 @@ export const SPEC_COMPONENT_IDS = [
     'content-layout',
     'context-menu',
     'context-menu-trigger',
+    'deck-slide',
     'description',
     'detail-panel',
     'dialog',
@@ -71,6 +72,7 @@ export const SPEC_COMPONENT_IDS = [
     'hover-card',
     'hover-card-content',
     'icon-button',
+    'inline-text',
     'input',
     'input-group',
     'kbd',

package/dist/index.d.ts

@@ -5,11 +5,11 @@
  * hashing. Build-time generation and the conformance harness live in
  * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
  */
-export type * from '../generated/typescript/blueprint.js';
-export type * from '../generated/typescript/catalog-schema.js';
-export type * from '../generated/typescript/diagnostics.js';
-export type * from '../generated/typescript/manifest.js';
-export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, type SpecComponentId, type SpecComponentProps, } from '../generated/typescript/vocabulary.js';
+export type * from './generated/typescript/blueprint.js';
+export type * from './generated/typescript/catalog-schema.js';
+export type * from './generated/typescript/diagnostics.js';
+export type * from './generated/typescript/manifest.js';
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, type SpecComponentId, type SpecComponentProps, } from './generated/typescript/vocabulary.js';
 export { canonicalJson, sha256 } from './canonical.js';
 export { CAPABILITIES, type Capability, type SpecPropKind, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from './catalog.js';
 export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';

package/dist/index.js

@@ -5,7 +5,7 @@
  * hashing. Build-time generation and the conformance harness live in
  * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
  */
-export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, } from "../generated/typescript/vocabulary.js";
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, } from "./generated/typescript/vocabulary.js";
 export { canonicalJson, sha256 } from "./canonical.js";
 export { CAPABILITIES, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from "./catalog.js";
 export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, validateInstance, } from "./dialect.js";

package/dist/validate.d.ts

@@ -1,4 +1,4 @@
-import type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation } from '../generated/typescript/diagnostics.js';
+import type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation } from './generated/typescript/diagnostics.js';
 import type { SpecCatalog } from './catalog.js';
 import { type Schema } from './dialect.js';
 export type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation };
@@ -10,7 +10,9 @@ export interface SpecDocuments {
  * Validate a blueprint envelope against the spec alone: the envelope schema,
  * then every node against the catalog vocabulary (closed ids, closed prop
  * names, prop kinds and enum values, required props, no platform-extension
- * props from data) and the declared profile. With `catalogHash`, an envelope
+ * props from data, a `slot` that names a slot prop of the parent) and the
+ * declared profile. A `when` condition is checked for shape only; the
+ * runtime formula parser checks its operands. With `catalogHash`, an envelope
  * bound to another catalog is refused. This is the shared, target-neutral
  * contract; URL policy, limits, grammar and rendering stay in the runtime
  * validators (`@texuli/catalog/validate`).

package/dist/validate.js

@@ -4,7 +4,9 @@ const MAX_TREE_DEPTH = 64;
  * Validate a blueprint envelope against the spec alone: the envelope schema,
  * then every node against the catalog vocabulary (closed ids, closed prop
  * names, prop kinds and enum values, required props, no platform-extension
- * props from data) and the declared profile. With `catalogHash`, an envelope
+ * props from data, a `slot` that names a slot prop of the parent) and the
+ * declared profile. A `when` condition is checked for shape only; the
+ * runtime formula parser checks its operands. With `catalogHash`, an envelope
  * bound to another catalog is refused. This is the shared, target-neutral
  * contract; URL policy, limits, grammar and rendering stay in the runtime
  * validators (`@texuli/catalog/validate`).
@@ -30,9 +32,10 @@ export function validateBlueprint(input, documents, options = {}) {
 export function validateTree(tree, catalog, options = {}) {
     const byId = new Map(catalog.components.map((c) => [c.id, c]));
     const out = [];
-    const visit = (node, path, depth) => {
+    const visit = (node, path, depth, parent) => {
         if (!isRecord(node) || typeof node.id !== 'string' || depth > MAX_TREE_DEPTH)
             return;
+        checkSlot(node.slot, parent, node.id, path, out);
         const component = byId.get(node.id);
         if (!component) {
             out.push({
@@ -55,13 +58,35 @@ export function validateTree(tree, catalog, options = {}) {
         }
         if (Array.isArray(node.children)) {
             node.children.forEach((child, index) => {
-                visit(child, `${path}.children[${index}]`, depth + 1);
+                visit(child, `${path}.children[${index}]`, depth + 1, component);
             });
         }
     };
-    visit(tree, options.path ?? '$', 0);
+    visit(tree, options.path ?? '$', 0, null);
     return out;
 }
+/**
+ * A node's `slot` (audit G04) must name a slot prop of its parent; omitted
+ * or `children` is the default slot. A root fills no slot. An unknown
+ * parent was already reported, so its children's slots are not judged.
+ */
+function checkSlot(slot, parent, id, path, out) {
+    if (slot === undefined || slot === 'children' || parent === undefined)
+        return;
+    const named = parent !== null &&
+        typeof slot === 'string' &&
+        parent.props.some((prop) => prop.kind === 'slot' && prop.name === slot);
+    if (named)
+        return;
+    out.push({
+        code: 'unknown-slot',
+        path: `${path}.slot`,
+        id,
+        message: parent === null
+            ? 'A root node fills no slot.'
+            : `"${String(slot)}" is not a slot of "${parent.id}".`,
+    });
+}
 function checkProps(props, component, path, out) {
     const given = isRecord(props) ? props : {};
     const id = component.id;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export declare const SPEC_VERSION = "0.1.0";
+export declare const SPEC_VERSION = "0.2.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export const SPEC_VERSION = '0.1.0';
+export const SPEC_VERSION = '0.2.0';

package/dist/versioning.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The spec's version history (`versions.json`): every released spec version
+ * pinned to the digest of its normative files, so the digest and the semantic
+ * version cannot drift apart. A normative change (schema, catalog projection,
+ * capability claim or fixture) changes the digest; it needs a new version
+ * and a new pin, with the change class the policy assigns to it.
+ */
+/** What a release changes, by the policy in the package README. */
+export type SpecChangeClass = 'patch' | 'minor' | 'major';
+export interface SpecVersionPin {
+    specVersion: string;
+    /** The spec digest of that release, or `null` for a release pinned retroactively without one. */
+    specDigest: string | null;
+    change: SpecChangeClass | 'initial';
+    summary: string;
+}
+export interface SpecVersionHistory {
+    releases: readonly SpecVersionPin[];
+}
+export interface VersionIssue {
+    version: string;
+    message: string;
+}
+/**
+ * The version that must follow `previous` for a change of `change` class.
+ * Before 1.0.0 any change to accepted data (minor or major class) bumps the
+ * minor number and a patch-class change bumps the patch; from 1.0.0 each
+ * class bumps its own number.
+ */
+export declare function nextSpecVersion(previous: string, change: SpecChangeClass): string;
+/**
+ * Check the history and that the newest release is the spec as built now:
+ * the same version and the same digest. Returns every problem; empty means
+ * the version and the digest agree.
+ */
+export declare function checkVersionHistory(history: SpecVersionHistory, current: {
+    specVersion: string;
+    specDigest: string;
+}): VersionIssue[];

package/dist/versioning.js

@@ -0,0 +1,87 @@
+/**
+ * The spec's version history (`versions.json`): every released spec version
+ * pinned to the digest of its normative files, so the digest and the semantic
+ * version cannot drift apart. A normative change (schema, catalog projection,
+ * capability claim or fixture) changes the digest; it needs a new version
+ * and a new pin, with the change class the policy assigns to it.
+ */
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+function parts(version) {
+    const match = SEMVER.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+/**
+ * The version that must follow `previous` for a change of `change` class.
+ * Before 1.0.0 any change to accepted data (minor or major class) bumps the
+ * minor number and a patch-class change bumps the patch; from 1.0.0 each
+ * class bumps its own number.
+ */
+export function nextSpecVersion(previous, change) {
+    const p = parts(previous);
+    if (!p)
+        throw new Error(`${previous}: not a semantic version`);
+    const [major, minor, patch] = p;
+    if (change === 'patch')
+        return `${major}.${minor}.${patch + 1}`;
+    if (major === 0 || change === 'minor')
+        return `${major}.${minor + 1}.0`;
+    return `${major + 1}.0.0`;
+}
+/**
+ * Check the history and that the newest release is the spec as built now:
+ * the same version and the same digest. Returns every problem; empty means
+ * the version and the digest agree.
+ */
+export function checkVersionHistory(history, current) {
+    const issues = [];
+    const releases = history.releases;
+    if (releases.length === 0) {
+        return [{ version: current.specVersion, message: 'versions.json lists no release.' }];
+    }
+    releases.forEach((release, index) => {
+        const { specVersion: version } = release;
+        if (!parts(version))
+            issues.push({ version, message: 'not a semantic version' });
+        if (release.specDigest !== null && !DIGEST.test(release.specDigest)) {
+            issues.push({ version, message: 'the digest is not a SHA-256 hex string' });
+        }
+        if (index === 0) {
+            if (release.change !== 'initial') {
+                issues.push({ version, message: 'the first release must have change "initial"' });
+            }
+            return;
+        }
+        const previous = releases[index - 1];
+        if (release.change === 'initial') {
+            issues.push({ version, message: 'only the first release is "initial"' });
+            return;
+        }
+        if (release.specDigest === null) {
+            issues.push({ version, message: 'only the first release may lack a digest' });
+        }
+        if (parts(previous.specVersion)) {
+            const expected = nextSpecVersion(previous.specVersion, release.change);
+            if (version !== expected) {
+                issues.push({
+                    version,
+                    message: `a ${release.change} change after ${previous.specVersion} is ${expected}`,
+                });
+            }
+        }
+    });
+    const newest = releases[releases.length - 1];
+    if (newest.specVersion !== current.specVersion) {
+        issues.push({
+            version: current.specVersion,
+            message: `the newest release in versions.json is ${newest.specVersion}, the spec is ${current.specVersion}`,
+        });
+    }
+    else if (newest.specDigest !== current.specDigest) {
+        issues.push({
+            version: current.specVersion,
+            message: 'the normative files changed without a new version: classify the change, bump SPEC_VERSION, regenerate, and append a release pinning the new digest',
+        });
+    }
+    return issues;
+}

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "@texuli/spec",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.3",
   "description": "The schema-first blueprint contract: JSON schemas, the catalog vocabulary, deterministic TypeScript and Kotlin projections, and the conformance harness.",
+  "keywords": [
+    "svelte",
+    "svelte-5",
+    "components",
+    "design-system",
+    "texuli"
+  ],
+  "homepage": "https://github.com/DailybotHQ/texuli#readme",
+  "bugs": "https://github.com/DailybotHQ/texuli/issues",
   "license": "MIT",
+  "author": "Dailybot, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DailybotHQ/texuli.git",
+    "directory": "packages/spec"
+  },
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -18,11 +33,6 @@
     }
   },
   "files": [
-    "dist",
-    "generated/typescript"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "next"
-  }
+    "dist"
+  ]
 }