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

package/README.md

@@ -11,6 +11,13 @@ 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.
 
+The package tarball build compiles `generated/typescript/` into the matching
+`dist/generated/typescript/` location. The source stays beside `src/` so the
+spec generator and integrity manifest keep their established output paths;
+the packer maps runtime and declaration imports to emitted `.js` and `.d.ts`
+files there. Kotlin projections remain generated text and are not part of the
+TypeScript package output.
+
 ## Layout
 
 | Path | What it holds |
@@ -18,9 +25,10 @@ or published to Maven.
 | `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 |
+| `fixtures/golden/` | Blueprints that must validate: a report, a dashboard, a proactive deck and a report with a named slot and a `when` condition (fictional data) |
+| `fixtures/invalid/` | Blueprints that must fail with exact diagnostic codes, one or more per code, including slot and condition cases (an undeclared or root `slot`, an unknown condition `op`, an extra condition field) |
 | `manifest.json` | The spec version, the dialect and a SHA-256 per normative file |
+| `versions.json` | Every released spec version pinned to its spec digest (not normative: it pins the normative files) |
 | `generated/typescript/`, `generated/kotlin/` | The projections. Never edit them |
 | `generated-manifest.json` | A SHA-256 per generated file |
 
@@ -40,7 +48,8 @@ maps. Anything else fails `checkSchemaDocument`, and generation refuses it.
   - `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,
+    platform-extension props from data, a node `slot` that names a slot prop
+    of its parent (`unknown-slot`), the portable profile failing closed,
     and an optional catalog binding);
   - `canonicalJson` and a synchronous `sha256`.
 - `@texuli/spec/codegen`, build time: `buildSpec`, `projectCatalog`,
@@ -84,10 +93,68 @@ pnpm exec tsx packages/spec/scripts/generate.ts --check    # fail on drift
   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.
+  every type it references and decodes closed;
+- the spec version and digest match the newest release in `versions.json`.
 
 When the catalog changes, refresh `components.json`, regenerate and review
-the diff.
+the diff. Then classify the change, bump the version, and pin it (see
+Versioning).
+
+## Versioning
+
+**The spec digest** is the SHA-256 of `manifest.json`'s canonical JSON: the
+spec version, the dialect and a digest per normative file (schemas,
+`catalog/components.json`, `catalog/capabilities.json` and every fixture).
+Every generated file carries it in its stamp (`// Spec 0.2.0, digest …`).
+The same normative files always give the same digest.
+
+**The version follows the digest.** Every normative change changes the
+digest, and a changed digest needs a new semantic version.
+`tests/versioning.test.ts` fails when the digest moves without one. The
+release goes in `versions.json`: its version, its digest, its change class
+and a one-line summary.
+
+| Class | What it covers | Before 1.0.0 | From 1.0.0 |
+| --- | --- | --- | --- |
+| patch | Nothing accepted changes: descriptions, diagnostic wording, a new fixture for behavior that already holds | patch | patch |
+| minor | Additive: optional fields, new catalog ids, new optional props, new diagnostic codes for data that was already refused, new named extensions. Existing portable fixtures still pass | minor | minor |
+| major | Removing or renaming ids, props or fields; changing a prop type; making something required; changing what accepted data means | minor | major |
+
+`nextSpecVersion(previous, class)` computes the step and
+`checkVersionHistory` enforces it. Before 1.0.0, any change to accepted data
+bumps the minor number. Moving to 1.0.0 is a release decision for the owner,
+not a side effect of a change. 0.1.0, the bootstrap, has no pinned digest:
+its normative files moved without a version until 0.2.0.
+
+**What a projection change means for consumers:**
+- **TypeScript (`@texuli/spec`):** a patch release leaves the generated types
+  and `SPEC_COMPONENT_IDS` alone, apart from the stamp. Code that compiled
+  against a minor release keeps compiling, but new optional fields and ids
+  can appear in data it reads. A major-class change (a minor bump before
+  1.0.0) may remove or retype what it relied on.
+- **Kotlin and native (`native/`):** `texuli-spec` compiles
+  `generated/kotlin` from this package, so a native build always matches the
+  checked-out spec. The generated 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. It does not pass silently. After a change, regenerate,
+  rebuild native, and refresh the conformance traces when goldens moved
+  (`pnpm exec tsx native/conformance/web/trace.ts --write`). Native
+  conformance compares the native refusals with every invalid fixture's
+  codes.
+- **Blueprints:** a blueprint binds to an exact catalog hash today. The
+  envelope field for a compatible spec range is **planned, not built**.
+  Until it exists, a consumer checks the spec version it ships against the
+  stamp of the spec it was built from.
+
+Migrations between versions (deterministic blueprint transforms tested per
+version pair) are **planned, not built**: nothing has needed one yet.
+
+
+## Named slots and conditions
+
+A node may carry `slot` (audit G04: the parent's named slot, a string such as
+`hero`) and `when` (audit G07: the blocks `Condition` AST that shows the node
+when true). Both match what `@texuli/catalog` renders.
 
 ## Not yet
 
@@ -96,3 +163,8 @@ the diff.
 - 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).
+- A full type for `when`. The dialect has no unions, so `condition` and
+  `numberFormula` are closed records whose `op` is an enum and whose operands
+  are typed (except `value`, which is a number for `num` and a formula for
+  `round` and `clamp`). Which operands each `op` needs, and the formula
+  limits, are checked by the runtime parser in `@texuli/blocks/formula`.

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.1",
   "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"
+  ]
 }