@texuli/spec 0.0.0-stage → 0.1.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @texuli/spec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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 |
+| --- | --- |
+| `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, 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 |
+
+## 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, 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`,
+  `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
+
+```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
+```
+
+## 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;
+- the spec version and digest match the newest release in `versions.json`.
+
+When the catalog changes, refresh `components.json`, regenerate and review
+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
+
+- 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).
+- 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/build.d.ts

@@ -0,0 +1,47 @@
+import type { Stamp } from './codegen/shared.js';
+import { SPEC_VERSION } from './version.js';
+export { SPEC_VERSION };
+/** Where normative files live inside the package. */
+export declare const NORMATIVE_DIRS: readonly ["schemas/", "catalog/", "fixtures/"];
+/** The schema documents, their generated names and output files. */
+export declare const SCHEMA_UNITS: readonly [{
+    readonly name: "blueprint";
+    readonly prefix: "Blueprint";
+    readonly ts: "blueprint.ts";
+    readonly kt: "Blueprint.kt";
+}, {
+    readonly name: "catalog";
+    readonly prefix: "Spec";
+    readonly ts: "catalog-schema.ts";
+    readonly kt: "CatalogSchema.kt";
+}, {
+    readonly name: "diagnostics";
+    readonly prefix: "Spec";
+    readonly ts: "diagnostics.ts";
+    readonly kt: "Diagnostics.kt";
+}, {
+    readonly name: "manifest";
+    readonly prefix: "Spec";
+    readonly ts: "manifest.ts";
+    readonly kt: "Manifest.kt";
+}];
+export declare const TS_OUT = "generated/typescript/";
+export declare const KOTLIN_OUT = "generated/kotlin/com/texuli/spec/";
+export interface SpecBuild {
+    /** `manifest.json`: the spec version and a digest per normative file. */
+    manifest: string;
+    /** The stamp every generated file carries. */
+    stamp: Stamp;
+    /** Generated path → content. */
+    generated: Readonly<Record<string, string>>;
+    /** `generated-manifest.json`: a digest per generated file. */
+    generatedManifest: string;
+}
+/**
+ * Build the whole spec from its normative files (path → exact text): the
+ * manifest, every TypeScript and Kotlin projection and the generated
+ * manifest. Pure and deterministic: the same files give byte-identical
+ * output, whatever order they are passed in. Throws when a schema leaves
+ * the dialect.
+ */
+export declare function buildSpec(files: Readonly<Record<string, string>>, specVersion?: string): SpecBuild;

package/dist/build.js

@@ -0,0 +1,65 @@
+import { canonicalJson, sha256 } from "./canonical.js";
+import { kotlinJsonRuntime, schemaToKotlin, vocabularyToKotlin } from "./codegen/kotlin.js";
+import { schemaToTypeScript, vocabularyToTypeScript } from "./codegen/typescript.js";
+import { DIALECT_URI } from "./dialect.js";
+import { formatJson } from "./format.js";
+import { SPEC_VERSION } from "./version.js";
+export { SPEC_VERSION };
+/** Where normative files live inside the package. */
+export const NORMATIVE_DIRS = ['schemas/', 'catalog/', 'fixtures/'];
+/** The schema documents, their generated names and output files. */
+export const SCHEMA_UNITS = [
+    { name: 'blueprint', prefix: 'Blueprint', ts: 'blueprint.ts', kt: 'Blueprint.kt' },
+    { name: 'catalog', prefix: 'Spec', ts: 'catalog-schema.ts', kt: 'CatalogSchema.kt' },
+    { name: 'diagnostics', prefix: 'Spec', ts: 'diagnostics.ts', kt: 'Diagnostics.kt' },
+    { name: 'manifest', prefix: 'Spec', ts: 'manifest.ts', kt: 'Manifest.kt' },
+];
+export const TS_OUT = 'generated/typescript/';
+export const KOTLIN_OUT = 'generated/kotlin/com/texuli/spec/';
+/**
+ * Build the whole spec from its normative files (path → exact text): the
+ * manifest, every TypeScript and Kotlin projection and the generated
+ * manifest. Pure and deterministic: the same files give byte-identical
+ * output, whatever order they are passed in. Throws when a schema leaves
+ * the dialect.
+ */
+export function buildSpec(files, specVersion = SPEC_VERSION) {
+    const paths = Object.keys(files).sort();
+    for (const path of paths) {
+        if (!NORMATIVE_DIRS.some((dir) => path.startsWith(dir)) || !path.endsWith('.json')) {
+            throw new Error(`${path}: not a normative spec file`);
+        }
+    }
+    const manifestData = {
+        specVersion,
+        dialect: DIALECT_URI,
+        files: Object.fromEntries(paths.map((path) => [path, sha256(files[path])])),
+    };
+    const stamp = { specVersion, specDigest: sha256(canonicalJson(manifestData)) };
+    const read = (path) => {
+        const text = files[path];
+        if (text === undefined)
+            throw new Error(`${path}: missing`);
+        return JSON.parse(text);
+    };
+    const generated = {};
+    for (const unit of SCHEMA_UNITS) {
+        const source = `schemas/${unit.name}.schema.json`;
+        const schemaUnit = { source, schema: read(source), prefix: unit.prefix };
+        generated[`${TS_OUT}${unit.ts}`] = schemaToTypeScript(schemaUnit, stamp);
+        generated[`${KOTLIN_OUT}${unit.kt}`] = schemaToKotlin(schemaUnit, stamp);
+    }
+    const catalog = read('catalog/components.json');
+    generated[`${TS_OUT}vocabulary.ts`] = vocabularyToTypeScript(catalog, stamp);
+    generated[`${KOTLIN_OUT}Vocabulary.kt`] = vocabularyToKotlin(catalog, stamp);
+    generated[`${KOTLIN_OUT}Json.kt`] = kotlinJsonRuntime(stamp);
+    const sorted = Object.fromEntries(Object.keys(generated)
+        .sort()
+        .map((path) => [path, generated[path]]));
+    const generatedManifest = formatJson({
+        specVersion,
+        dialect: DIALECT_URI,
+        files: Object.fromEntries(Object.entries(sorted).map(([path, text]) => [path, sha256(text)])),
+    });
+    return { manifest: formatJson(manifestData), stamp, generated: sorted, generatedManifest };
+}

package/dist/canonical.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic serialization and hashing, with no runtime dependency: the
+ * same input gives the same bytes and digest in every runtime.
+ */
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit at every depth, no
+ * whitespace, `undefined` fields dropped. Throws on values JSON cannot carry
+ * exactly (functions, non-finite numbers, cycles).
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Pretty canonical JSON for committed files: sorted keys, two-space indent,
+ * a trailing newline. Byte-stable for the same data.
+ */
+export declare function prettyJson(value: unknown): string;
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes (FIPS 180-4), synchronous. */
+export declare function sha256(text: string): string;

package/dist/canonical.js

@@ -0,0 +1,131 @@
+/**
+ * Deterministic serialization and hashing, with no runtime dependency: the
+ * same input gives the same bytes and digest in every runtime.
+ */
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit at every depth, no
+ * whitespace, `undefined` fields dropped. Throws on values JSON cannot carry
+ * exactly (functions, non-finite numbers, cycles).
+ */
+export function canonicalJson(value) {
+    return encode(value, new Set());
+}
+function encode(value, stack) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('canonicalJson: non-finite number');
+        return JSON.stringify(value);
+    }
+    if (typeof value !== 'object')
+        throw new TypeError(`canonicalJson: ${typeof value} value`);
+    if (stack.has(value))
+        throw new TypeError('canonicalJson: cycle');
+    stack.add(value);
+    let out;
+    if (Array.isArray(value)) {
+        out = `[${value.map((item) => encode(item === undefined ? null : item, stack)).join(',')}]`;
+    }
+    else {
+        const record = value;
+        const keys = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort();
+        out = `{${keys.map((key) => `${JSON.stringify(key)}:${encode(record[key], stack)}`).join(',')}}`;
+    }
+    stack.delete(value);
+    return out;
+}
+/**
+ * Pretty canonical JSON for committed files: sorted keys, two-space indent,
+ * a trailing newline. Byte-stable for the same data.
+ */
+export function prettyJson(value) {
+    return `${JSON.stringify(JSON.parse(canonicalJson(value)), null, 2)}\n`;
+}
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** UTF-8 bytes of a string (no `TextEncoder` needed). */
+function utf8(text) {
+    const bytes = [];
+    for (const char of text) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 0x80)
+            bytes.push(code);
+        else if (code < 0x800)
+            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+        else if (code < 0x10000)
+            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        else
+            bytes.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    }
+    return bytes;
+}
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes (FIPS 180-4), synchronous. */
+export function sha256(text) {
+    const bytes = utf8(text);
+    const bitLength = bytes.length * 8;
+    bytes.push(0x80);
+    while (bytes.length % 64 !== 56)
+        bytes.push(0);
+    const high = Math.floor(bitLength / 0x100000000);
+    for (const word of [high, bitLength >>> 0]) {
+        bytes.push((word >>> 24) & 0xff, (word >>> 16) & 0xff, (word >>> 8) & 0xff, word & 0xff);
+    }
+    const hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let offset = 0; offset < bytes.length; offset += 64) {
+        for (let i = 0; i < 16; i += 1) {
+            const at = offset + i * 4;
+            w[i] =
+                ((bytes[at] ?? 0) << 24) |
+                    ((bytes[at + 1] ?? 0) << 16) |
+                    ((bytes[at + 2] ?? 0) << 8) |
+                    (bytes[at + 3] ?? 0);
+        }
+        for (let i = 16; i < 64; i += 1) {
+            const a = w[i - 15] ?? 0;
+            const b = w[i - 2] ?? 0;
+            const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+            const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+            w[i] = ((w[i - 16] ?? 0) + s0 + (w[i - 7] ?? 0) + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = hash;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + s1 + ch + (K[i] ?? 0) + (w[i] ?? 0)) >>> 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^
+                (a & c) ^
+                (b & c);
+            const t2 = (s0 + maj) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        const round = [a, b, c, d, e, f, g, h];
+        for (let i = 0; i < 8; i += 1)
+            hash[i] = ((hash[i] ?? 0) + (round[i] ?? 0)) >>> 0;
+    }
+    return Array.from(hash, (word) => word.toString(16).padStart(8, '0')).join('');
+}

package/dist/catalog.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The spec's catalog vocabulary (`catalog/components.json`) and its
+ * 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';
+export type { SpecCatalog, SpecComponent, SpecProp };
+export declare const CAPABILITIES: readonly ["portable-core", "web-only", "native-only", "unknown"];
+export type Capability = SpecComponent['capability'];
+export type SpecPropKind = SpecProp['kind'];
+/** Prop kinds that cannot cross the shared boundary: they become web extensions. */
+export declare const WEB_ONLY_KINDS: readonly SpecPropKind[];
+/**
+ * Props that are web implementation details whatever their kind (spec/Compose
+ * design §6): CSS hooks and the chart renderer choice (`svg`, `canvas`, `auto`).
+ */
+export declare const WEB_ONLY_PROP_NAMES: readonly string[];
+/** The fields of a built catalog the projection reads (no dependency on the catalog package). */
+export interface BuiltCatalogLike {
+    entries: readonly {
+        id: string;
+        label: string;
+        summary: string;
+        group: string;
+        tier: 'app' | 'content';
+        emit: readonly string[];
+        props: readonly {
+            name: string;
+            kind: SpecPropKind;
+            required?: boolean;
+            enumValues?: readonly string[];
+        }[];
+    }[];
+}
+/**
+ * Project a built catalog into the spec vocabulary. Deterministic: components
+ * sorted by id, props by name, emit tiers sorted. Capability is `unknown`
+ * unless `capabilities` (the reviewed `catalog/capabilities.json`) records an
+ * audited value (ADR-003: no id is portable until audited).
+ */
+export declare function projectCatalog(catalog: BuiltCatalogLike, catalogHash: string, capabilities?: Readonly<Record<string, Capability>>): SpecCatalog;

package/dist/catalog.js

@@ -0,0 +1,45 @@
+/**
+ * The spec's catalog vocabulary (`catalog/components.json`) and its
+ * 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.
+ */
+export const CAPABILITIES = ['portable-core', 'web-only', 'native-only', 'unknown'];
+/** Prop kinds that cannot cross the shared boundary: they become web extensions. */
+export const WEB_ONLY_KINDS = ['slot', 'event', 'unknown'];
+/**
+ * Props that are web implementation details whatever their kind (spec/Compose
+ * design §6): CSS hooks and the chart renderer choice (`svg`, `canvas`, `auto`).
+ */
+export const WEB_ONLY_PROP_NAMES = ['class', 'className', 'style', 'renderer'];
+/**
+ * Project a built catalog into the spec vocabulary. Deterministic: components
+ * sorted by id, props by name, emit tiers sorted. Capability is `unknown`
+ * unless `capabilities` (the reviewed `catalog/capabilities.json`) records an
+ * audited value (ADR-003: no id is portable until audited).
+ */
+export function projectCatalog(catalog, catalogHash, capabilities = {}) {
+    const byName = (a, b) => (a.name < b.name ? -1 : 1);
+    const components = [...catalog.entries]
+        .sort((a, b) => (a.id < b.id ? -1 : 1))
+        .map((entry) => ({
+        id: entry.id,
+        label: entry.label,
+        summary: entry.summary,
+        group: entry.group,
+        placement: entry.tier,
+        emit: [...entry.emit].sort(),
+        capability: Object.hasOwn(capabilities, entry.id)
+            ? capabilities[entry.id]
+            : 'unknown',
+        props: [...entry.props].sort(byName).map((prop) => ({
+            name: prop.name,
+            kind: prop.kind,
+            ...(prop.required === true ? { required: true } : {}),
+            ...(prop.enumValues ? { enumValues: [...prop.enumValues] } : {}),
+            ...(WEB_ONLY_KINDS.includes(prop.kind) || WEB_ONLY_PROP_NAMES.includes(prop.name)
+                ? { extension: 'web' }
+                : {}),
+        })),
+    }));
+    return { catalogHash, components };
+}

package/dist/codegen/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@texuli/spec/codegen` — build-time tooling: deterministic generation of
+ * the manifests and the TypeScript and Kotlin projections, the catalog
+ * projection, the committed-file JSON format and the conformance harness.
+ * Pure functions: callers read and write the files.
+ */
+export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, type SpecBuild, TS_OUT, } from '../build.js';
+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

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/spec/codegen` — build-time tooling: deterministic generation of
+ * the manifests and the TypeScript and Kotlin projections, the catalog
+ * projection, the committed-file JSON format and the conformance harness.
+ * Pure functions: callers read and write the files.
+ */
+export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, TS_OUT, } from "../build.js";
+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/dist/codegen/kotlin.d.ts

@@ -0,0 +1,18 @@
+import type { SpecCatalog } from '../catalog.js';
+import { type SchemaUnit, type Stamp } from './shared.js';
+/**
+ * Deterministic Kotlin projections of the spec, written as committed text
+ * (no Kotlin toolchain here): data classes, closed enums and static
+ * decoders over a small `JsonValue` model, with no library dependency.
+ * Decoders check JSON types, required and unknown fields, enums and
+ * constants; patterns and limits stay with the shared validator.
+ */
+export declare const KOTLIN_PACKAGE = "com.texuli.spec";
+/** A Kotlin string literal (escapes backslash, quote, dollar and controls). */
+export declare function kotlinString(value: string): string;
+/** One schema document as a Kotlin file of data classes, enums and decoders. */
+export declare function schemaToKotlin(unit: SchemaUnit, stamp: Stamp): string;
+/** The JSON model and decode helpers every generated decoder uses. */
+export declare function kotlinJsonRuntime(stamp: Stamp): string;
+/** The catalog vocabulary as a Kotlin registry of `SpecComponent` values. */
+export declare function vocabularyToKotlin(catalog: SpecCatalog, stamp: Stamp): string;