@verevoir/design-gate 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,20 @@
 # @verevoir/design-gate
 
-Zero-dependency deterministic verifier for a design pack: DTCG token validation,
-regenerate-diff of generated value views, and value-drift checks over the concept
-docs. Node built-ins only — runs anywhere with no install.
+The design substrate, in two layers:
 
-The **same code** the design capabilities emit into a produced pack (for that
-pack's CI) **and** the runtime imports to enforce a capability's
-`verify: design-pack` postcondition (STDIO-451) — one source, two consumers.
+- **The gate** (`.` → [`design/`](design/README.md)) — a zero-dependency
+  deterministic verifier for a design pack: DTCG token validation, regenerate-diff
+  of generated value views, and value-drift checks over the concept docs. Node
+  built-ins only — runs anywhere with no install. The **same code** the design
+  capabilities emit into a produced pack (for that pack's CI) **and** the runtime
+  imports to enforce a capability's `verify: design-pack` postcondition (STDIO-451)
+  — one source, two consumers.
+- **The surface** (`./surface` → [`surface/surface.ts`](surface/surface.ts)) — the
+  typed `DesignSurface` contract (the design interlingua) with its `validateSurface`
+  gate and `merge`/`synthesise`. Its token layer is validated by delegating to the
+  gate's `validateDtcg`, so the tokens are the token-layer slice of one surface
+  rather than a separate DTCG pipeline (STDIO-524). This layer is TypeScript and
+  depends on `zod`; the gate stays zero-dependency and is what ships into packs.
 
 ## Use
 

package/design/build-artefacts.mjs

@@ -0,0 +1,109 @@
+// Deterministic build-artefact presence check. Given a list of file paths (e.g.
+// the output tree of a produced design pack or a PR's changed files), flags any
+// path that sits inside a build-output, dependency-cache, or generated directory
+// that must never enter version control — enforcing `track-only-intended-files`.
+//
+// Scope is deliberately limited to artefact *directory* conventions. These are
+// stable across languages (node_modules/, dist/, target/, obj/, __pycache__/…)
+// and rarely false-positive, so they earn a deterministic check. We do NOT
+// enumerate compiled file *extensions*: that list can't be completed (the next
+// stack ships output we never listed — a silent miss), and a design pack
+// legitimately commits binaries (fonts, icon files, images), so matching by
+// extension is both incomplete and occasionally wrong. Detecting whether a
+// stray committed file is an artefact across stacks we've never seen is a
+// judgment, not a regex — it belongs to the antagonistic reviewer's rubric,
+// where example-quality already lives.
+//
+// Zero dependencies (Node built-ins only). Pure: same paths → same findings.
+
+// Segment-level patterns: any path component (between slashes) that matches is
+// an artefact directory. Checked case-insensitively so "Node_Modules" etc. also
+// flag. Anchored to a segment boundary so "distribution/" does not trigger on
+// "dist/".
+const ARTEFACT_DIRS = [
+  /^node_modules$/i,
+  /^\.npm$/i,
+  /^dist$/i,
+  /^build$/i,
+  /^out$/i,
+  /^\.next$/i,
+  /^\.nuxt$/i,
+  /^\.svelte-kit$/i,
+  /^target$/i,
+  /^bin$/i,
+  /^obj$/i,
+  /^__pycache__$/i,
+  /^\.mypy_cache$/i,
+  /^\.pytest_cache$/i,
+  /^\.ruff_cache$/i,
+  /^\.gradle$/i,
+  /^\.nuget$/i,
+  /^packages$/i,   // NuGet packages restore dir
+  /^vendor$/i,
+  /^\.cache$/i,
+  /^coverage$/i,
+  /^\.coverage$/i,
+  /^htmlcov$/i,
+  /^\.turbo$/i,
+  /^\.parcel-cache$/i,
+];
+
+/** Normalise a path to forward-slash segments, filtering empty parts produced by
+ * leading slashes or doubled separators. */
+function segments(p) {
+  return p.replace(/\\/g, '/').split('/').filter(Boolean);
+}
+
+/**
+ * Check a list of file paths for committed build artefacts. Returns a flat list
+ * of findings `{ code, path, message }` — one per offending path — empty when
+ * no artefacts are detected.
+ *
+ * Only artefact *directories* are flagged (see the module header for why file
+ * extensions are deliberately out of scope).
+ *
+ * @param {string[]} paths - File paths to inspect (relative or absolute; both
+ *   `/`-separated and `\`-separated are handled).
+ * @returns {{ code: string, path: string, message: string }[]}
+ */
+export function checkBuildArtefacts(paths) {
+  if (!Array.isArray(paths)) return [];
+
+  const findings = [];
+
+  for (const rawPath of paths) {
+    if (typeof rawPath !== 'string') continue;
+
+    const segs = segments(rawPath);
+    if (segs.length === 0) continue;
+
+    // If ANY segment is an artefact directory, the path is flagged regardless of
+    // what follows it — a file deep inside node_modules/ is as bad as
+    // node_modules/ itself. The final segment is included so a path that ends on
+    // the directory name (no trailing slash, e.g. "dist") is caught too.
+    const artefactSeg = segs.find((seg) => ARTEFACT_DIRS.some((re) => re.test(seg)));
+    if (artefactSeg === undefined) continue;
+
+    const isLeaf = artefactSeg === segs[segs.length - 1];
+    findings.push({
+      code: 'COMMITTED_BUILD_ARTEFACT',
+      path: rawPath,
+      message: isLeaf
+        ? `path "${rawPath}" is a build/dependency directory that must not be committed — add it to .gitignore and remove it from the index.`
+        : `path "${rawPath}" is inside a build/dependency directory ("${artefactSeg}/") that must not be committed — add it to .gitignore and remove it from the index.`,
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Aggregate helper: run the artefact check and return `{ ok, findings }`.
+ *
+ * @param {string[]} paths - File paths to inspect.
+ * @returns {{ ok: boolean, findings: { code: string, path: string, message: string }[] }}
+ */
+export function verifyBuildArtefacts(paths) {
+  const findings = checkBuildArtefacts(paths);
+  return { ok: findings.length === 0, findings };
+}

package/design/dtcg.d.mts

@@ -0,0 +1,19 @@
+// Types for the zero-dependency gate module `dtcg.mjs`, hand-written because the
+// gate ships as plain ESM with no build. Only the surface's consumers are typed
+// here; the runtime is `dtcg.mjs`.
+
+/** A single DTCG validation finding, in tree order. */
+export interface DtcgFinding {
+  path: string;
+  code: string;
+  message: string;
+}
+
+/** Validate a parsed DTCG token tree; returns a flat list of findings (empty when
+ * well-formed). Pure and deterministic. */
+export function validateDtcg(root: unknown, opts?: { schema?: string }): DtcgFinding[];
+
+export const DTCG_SCHEMA: string;
+export function isRef(v: unknown): boolean;
+export function refPath(v: unknown): string | null;
+export function resolvedLiteral(root: unknown, value: unknown): unknown;

package/design/index.mjs

@@ -8,3 +8,5 @@ export { renderTokenView, checkView, GENERATED_MARK } from './generate.mjs';
 export { validateDtcg, DTCG_SCHEMA, isRef, refPath, resolvedLiteral } from './dtcg.mjs';
 export { tokenLiterals, findValueDrift } from './value-drift.mjs';
 export { runGate } from './gate.mjs';
+export { checkTokenCompleteness, verifyTokenCompleteness } from './token-completeness.mjs';
+export { checkBuildArtefacts, verifyBuildArtefacts } from './build-artefacts.mjs';

package/design/token-completeness.mjs

@@ -0,0 +1,272 @@
+// Deterministic token-system completeness check. Detects colour-only or partial
+// token systems — where the semantic/alias layer, typography, spacing, or
+// borders/radii are absent — so a capability execution that produces only a
+// colour palette is surfaced as incomplete rather than silently accepted as done.
+//
+// It also checks description coverage — that groups and the semantic/role layer
+// carry a $description so the file is legible without external documentation —
+// while exempting raw primitive scale steps, which would otherwise false-positive
+// on every legitimate 50→950 ramp.
+//
+// Explicitly out of scope: example quality (server vs. real usage vs. toy
+// snippets), whether inline provenance is genuinely the source form, and whether
+// the file is leaf-inline rather than sprawled — those are prose-rubric judgments
+// for an antagonistic reviewer, not deterministic structural checks. Only
+// structural completeness and description coverage are checked here.
+//
+// Usage: import checkTokenCompleteness / verifyTokenCompleteness or
+// checkDescriptionCoverage / verifyDescriptionCoverage; pure and zero-dependency
+// (Node built-ins only).
+
+const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const isRef = (v) => typeof v === 'string' && /^\{[^}]+\}$/.test(v.trim());
+
+// Group-name patterns for each dimension, matched case-insensitively against
+// top-level key names. Patterns lean broad: a valid token file will use names
+// like "color"/"colour", "spacing"/"space"/"gap", "typography"/"type"/"font",
+// "border"/"radius"/"radii". A file that uses none of these names for its groups
+// is unlikely to be a full system — the false-positive risk is low.
+const COLOUR_NAMES = /^colou?r(?:s)?$|^palette$|^brand$/i;
+const TYPOGRAPHY_NAMES = /^typograph|^type$|^font|^text$/i;
+const SPACING_NAMES = /^spacing$|^space$|^gap$|^size$|^scale$/i;
+const BORDER_NAMES = /^border|^radius$|^radii$|^corner$/i;
+
+/** A node is a non-scalar group: an object carrying child keys that are not DTCG
+ * metadata (not `$`-prefixed). A token group OR a composite DTCG group qualifies. */
+const hasChildren = (node) =>
+  isObject(node) && Object.keys(node).some((k) => !k.startsWith('$') && isObject(node[k]));
+
+/** Collect all token $value strings in the tree (aliases and literals alike).
+ * Used to detect whether any alias/semantic layer exists anywhere in the tree
+ * — not just at the top level. */
+function collectValues(node, out = []) {
+  if (!isObject(node)) return out;
+  if ('$value' in node) out.push(node.$value);
+  for (const [k, v] of Object.entries(node)) if (!k.startsWith('$')) collectValues(v, out);
+  return out;
+}
+
+/** Whether the tree contains at least one alias/reference token — a token whose
+ * `$value` is `{path.to.another.token}`. The presence of such a token indicates
+ * a semantic or role layer exists (palette tokens are typically raw values;
+ * role/alias tokens reference them). */
+function hasAliasLayer(root) {
+  return collectValues(root).some(isRef);
+}
+
+/** Whether the top-level structure contains at least one non-empty group whose
+ * name matches the given pattern. `hasValue` is true when at least one token
+ * (any token, not just a raw-value one) exists under that group — the group
+ * must be non-trivially populated, not just an empty shell. */
+function hasNonEmptyGroup(root, pattern) {
+  return Object.entries(root)
+    .filter(([k]) => !k.startsWith('$') && pattern.test(k))
+    .some(([, v]) => hasChildren(v));
+}
+
+/** Whether the tree contains any tokens at all — used to distinguish a genuinely
+ * empty file (no findings emitted; invalid DTCG is the DTCG gate's concern) from
+ * a partial system. An empty tree cannot meaningfully be called colour-only. */
+function hasAnyToken(node) {
+  if (!isObject(node)) return false;
+  if ('$value' in node) return true;
+  return Object.entries(node).some(([k, v]) => !k.startsWith('$') && hasAnyToken(v));
+}
+
+/** Whether the tree contains any non-colour tokens (any group not matching colour
+ * names that has at least one token). Used for the COLOUR_ONLY detection: if the
+ * only populated groups are colour groups, the system is colour-only. */
+function hasNonColourTokens(root) {
+  return Object.entries(root)
+    .filter(([k]) => !k.startsWith('$') && !COLOUR_NAMES.test(k))
+    .some(([, v]) => hasAnyToken(v));
+}
+
+/**
+ * Check a parsed DTCG token tree for system completeness. Returns a flat list of
+ * findings `{ code, message }` — empty when the system looks complete.
+ *
+ * Findings emitted:
+ *   COLOUR_ONLY           — only colour groups are present; all other dimensions absent
+ *   MISSING_SEMANTIC_LAYER — no alias/reference token found anywhere; role tokens absent
+ *   MISSING_TYPOGRAPHY     — no typography/type/font group present or non-empty
+ *   MISSING_SPACING        — no spacing/space/gap group present or non-empty
+ *   MISSING_BORDER_RADIUS  — no border/radius group present or non-empty
+ *
+ * The check is structural and heuristic — it detects clearly absent dimensions
+ * by name-matching top-level groups and inspecting $value strings. It will not
+ * false-positive a legitimately complete file that uses standard DTCG group names,
+ * and will not flag component-level tokens as required (they are optional per the
+ * done-well bar stated in the capability). A colour-only tree may produce multiple
+ * findings (one COLOUR_ONLY plus the individual MISSING_* findings); callers may
+ * use COLOUR_ONLY as the primary signal and suppress or include the rest.
+ *
+ * @param {object} root - A parsed DTCG token object (the result of JSON.parse on
+ *   a *.tokens.json file). Non-objects, null, and arrays are treated as empty and
+ *   return no findings (DTCG validation is the validateDtcg gate's concern).
+ * @returns {{ code: string, message: string }[]}
+ */
+export function checkTokenCompleteness(root) {
+  if (!isObject(root)) return [];
+  if (!hasAnyToken(root)) return [];
+
+  const findings = [];
+
+  // COLOUR_ONLY: tokens exist but none outside colour groups.
+  if (!hasNonColourTokens(root)) {
+    findings.push({
+      code: 'COLOUR_ONLY',
+      message:
+        'token file contains only colour tokens — a full system requires a semantic/alias layer, typography, spacing, and borders/radii.',
+    });
+  }
+
+  // MISSING_SEMANTIC_LAYER: no alias reference found anywhere in the tree.
+  if (!hasAliasLayer(root)) {
+    findings.push({
+      code: 'MISSING_SEMANTIC_LAYER',
+      message:
+        'no alias/reference tokens found — a full system needs a semantic layer of role tokens (e.g. {color.brand.primary}) that reference palette values.',
+    });
+  }
+
+  // MISSING_TYPOGRAPHY: no typography/type/font group.
+  if (!hasNonEmptyGroup(root, TYPOGRAPHY_NAMES)) {
+    findings.push({
+      code: 'MISSING_TYPOGRAPHY',
+      message:
+        'no typography group found (expected a top-level "typography", "type", or "font" group) — font families, sizes, weights, and line-heights must be tokenised.',
+    });
+  }
+
+  // MISSING_SPACING: no spacing/space/gap group.
+  if (!hasNonEmptyGroup(root, SPACING_NAMES)) {
+    findings.push({
+      code: 'MISSING_SPACING',
+      message:
+        'no spacing group found (expected a top-level "spacing", "space", "gap", or "scale" group) — spacing and layout sizing must be tokenised.',
+    });
+  }
+
+  // MISSING_BORDER_RADIUS: no border/radius group.
+  if (!hasNonEmptyGroup(root, BORDER_NAMES)) {
+    findings.push({
+      code: 'MISSING_BORDER_RADIUS',
+      message:
+        'no border/radius group found (expected a top-level "border", "radius", "radii", or "corner" group) — border widths and radii must be tokenised.',
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Aggregate helper: run the completeness check and return `{ ok, findings }`.
+ * `ok` is true only when there are no findings.
+ *
+ * @param {object} root - A parsed DTCG token object.
+ * @returns {{ ok: boolean, findings: { code: string, message: string }[] }}
+ */
+export function verifyTokenCompleteness(root) {
+  const findings = checkTokenCompleteness(root);
+  return { ok: findings.length === 0, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Description coverage
+//
+// A token file is read far more often than it is written. The readability bar
+// (see generate-design-tokens) is that groups and the semantic/role layer carry
+// a $description so a consumer learns the system from the file, not a wiki. Raw
+// primitive scale steps (a 50→950 colour ramp, an 8px/16px spacing scale) are
+// deliberately exempt: requiring a description on each step would false-positive
+// on every legitimate scale, and the group's own description already says what
+// the scale is and how to choose within it.
+// ---------------------------------------------------------------------------
+
+/** A leaf token: a node carrying a `$value`. */
+const isToken = (node) => isObject(node) && '$value' in node;
+
+/** A semantic/alias token: a leaf whose `$value` references another token
+ * (`{path.to.token}`). These are the consumption surface a consumer reaches for,
+ * so each must say what it is for — unlike a raw primitive whose meaning is its
+ * position in a scale. */
+const isAliasToken = (node) => isToken(node) && isRef(node.$value);
+
+/** A group is a raw primitive scale when every direct token child holds a raw
+ * (non-alias) value — e.g. `blue: { 50: {…}, 100: {…} }` or `space: { 1: {…} }`.
+ * Such a group's steps are exempt from per-step descriptions; the group itself
+ * still carries one. A group with no direct token children (only sub-groups) is
+ * not a scale — it is a sectioning group and is held to the group bar. */
+function isRawScaleGroup(node) {
+  const tokenChildren = Object.entries(node)
+    .filter(([k]) => !k.startsWith('$'))
+    .map(([, v]) => v)
+    .filter(isToken);
+  return tokenChildren.length > 0 && tokenChildren.every((t) => !isRef(t.$value));
+}
+
+/** Walk the tree, collecting the human-readable path of every node that should
+ * carry a `$description` but does not: every group, and every semantic/alias
+ * token. Raw primitive leaf tokens are never required to carry one. */
+function collectMissingDescriptions(node, path, out) {
+  if (!isObject(node)) return;
+
+  if (isToken(node)) {
+    if (isAliasToken(node) && typeof node.$description !== 'string') {
+      out.push({ path, kind: 'semantic token' });
+    }
+    return;
+  }
+
+  if (hasChildren(node)) {
+    if (typeof node.$description !== 'string' && !isRawScaleGroup(node)) {
+      out.push({ path, kind: 'group' });
+    }
+  }
+
+  for (const [k, v] of Object.entries(node)) {
+    if (k.startsWith('$')) continue;
+    collectMissingDescriptions(v, path ? `${path}.${k}` : k, out);
+  }
+}
+
+/**
+ * Check a parsed DTCG token tree for description coverage. Returns a flat list of
+ * findings `{ code, message }` — empty when every group and semantic/alias token
+ * carries a `$description`. Raw primitive scale steps are not required to.
+ *
+ * Findings emitted:
+ *   MISSING_DESCRIPTIONS — one finding listing the groups and/or semantic tokens
+ *                          that lack a `$description`.
+ *
+ * @param {object} root - A parsed DTCG token object.
+ * @returns {{ code: string, message: string }[]}
+ */
+export function checkDescriptionCoverage(root) {
+  if (!isObject(root)) return [];
+  if (!hasAnyToken(root)) return [];
+
+  const missing = [];
+  collectMissingDescriptions(root, '', missing);
+  if (missing.length === 0) return [];
+
+  const where = missing.map((m) => `${m.path} (${m.kind})`).join(', ');
+  return [
+    {
+      code: 'MISSING_DESCRIPTIONS',
+      message: `${missing.length} group(s) and/or semantic token(s) lack a $description — a consumer must reach for external docs to know their purpose: ${where}.`,
+    },
+  ];
+}
+
+/**
+ * Aggregate helper: run the description-coverage check and return `{ ok, findings }`.
+ *
+ * @param {object} root - A parsed DTCG token object.
+ * @returns {{ ok: boolean, findings: { code: string, message: string }[] }}
+ */
+export function verifyDescriptionCoverage(root) {
+  const findings = checkDescriptionCoverage(root);
+  return { ok: findings.length === 0, findings };
+}

package/design/value-drift.mjs

@@ -2,11 +2,11 @@
 // concept doc points at it, never re-types it. This asserts no value-free doc
 // contains a literal token value. It is deliberately high-signal, not
 // exhaustive: it matches only DISTINCTIVE literals (a hex colour, a dimension
-// carrying a unit, a colour function, a percentage) where an occurrence in prose
-// is unambiguously a re-typed value; bare unitless numbers (font weights, a
-// type-scale step) are owned by the generated value views, not grepped here,
-// because "700" in prose is all noise. Fenced code blocks are skipped — example
-// code is meant to carry real values.
+// carrying a unit, a colour function, a font-family stack) where an occurrence
+// in prose is unambiguously a re-typed value; bare unitless numbers (font
+// weights, a type-scale step) are owned by the generated value views, not
+// grepped here, because "700" in prose is all noise. Fenced code blocks are
+// skipped — example code is meant to carry real values.
 
 const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
 const isRef = (v) => typeof v === 'string' && /^\{[^}]+\}$/.test(v.trim());
@@ -31,16 +31,37 @@ function literalsOf(value) {
   return out;
 }
 
+/** Extract a font-family literal for a DTCG `fontFamily` token `$value`. Only
+ * array values (full font stacks like `["Inter", "system-ui", "sans-serif"]`)
+ * are collected — their comma-separated form is distinctive enough in prose that
+ * a match is unambiguously a re-typed value. A single-family string ("Inter") is
+ * deliberately skipped: a bare font name is too common in ordinary prose to flag
+ * safely. Returns the lowercase comma-separated stack, or null if not flaggable. */
+function fontFamilyLiteral(value) {
+  if (Array.isArray(value) && value.length > 0)
+    return value.map((s) => String(s)).join(', ').toLowerCase();
+  return null;
+}
+
 /** The set of distinctive value literals a doc must not re-type. Walks the token
- * tree collecting every concrete `$value` (aliases are pointers, so skipped). */
+ * tree collecting every concrete `$value` (aliases are pointers, so skipped).
+ * Carries the inherited `$type` so font-family stacks under a typed group are
+ * also captured. */
 export function tokenLiterals(root) {
   const set = new Set();
-  const walk = (node) => {
+  const walk = (node, inheritedType) => {
     if (!isObject(node)) return;
-    if ('$value' in node) for (const lit of literalsOf(node.$value)) set.add(lit);
-    for (const [k, v] of Object.entries(node)) if (!k.startsWith('$') && isObject(v)) walk(v);
+    const type = '$type' in node ? node.$type : inheritedType;
+    if ('$value' in node) {
+      for (const lit of literalsOf(node.$value)) set.add(lit);
+      if (type === 'fontFamily') {
+        const lit = fontFamilyLiteral(node.$value);
+        if (lit) set.add(lit);
+      }
+    }
+    for (const [k, v] of Object.entries(node)) if (!k.startsWith('$') && isObject(v)) walk(v, type);
   };
-  walk(root);
+  walk(root, undefined);
   return set;
 }
 

package/design/verify-pack.mjs

@@ -75,10 +75,13 @@ export function verifyFiles(files) {
         message: `generated view is missing or stale — run: node tooling/design/generate.mjs ${tp} ${viewPath}`,
       });
 
-    // Concept docs: the `.md` files under this token file's `design-language/` dir.
-    const dlPrefix = tp.replace(/tokens\/[^/]+\.tokens\.json$/, '');
+    // Concept docs: the `.md` files under the reference-library root (the parent
+    // of `design-language/`). Strip `design-language/tokens/<name>.tokens.json`
+    // to reach that root so sibling dirs (`brand/`, `content/`, `accessibility/`,
+    // `media-types/`, …) are scanned alongside `design-language/` itself.
+    const refRoot = tp.replace(/design-language\/tokens\/[^/]+\.tokens\.json$/, '');
     const docs = [...map.entries()]
-      .filter(([p]) => p.endsWith('.md') && p.startsWith(dlPrefix))
+      .filter(([p]) => p.endsWith('.md') && p.startsWith(refRoot))
       .map(([path, text]) => ({ path, text: String(text ?? '') }));
     for (const d of runGate({ tokens, docs }).drift)
       findings.push({

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@verevoir/design-gate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Zero-dependency deterministic design verifier: DTCG token validation, regenerate-diff of generated views, and value-drift checks over a design pack. The same code the design capabilities emit into a produced pack (its CI) and the runtime imports to enforce a capability's `verify: design-pack` postcondition.",
+  "description": "The design substrate: a zero-dependency deterministic design gate (DTCG token validation, regenerate-diff of generated views, value-drift checks) that ships into a produced pack's CI, plus the typed DesignSurface contract (`./surface`) the tooling reasons over. The gate is the same code the design capabilities emit into a pack and the runtime imports to enforce a capability's `verify: design-pack` postcondition.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,18 +10,35 @@
     "directory": "tooling"
   },
   "exports": {
-    ".": "./design/index.mjs"
+    ".": "./design/index.mjs",
+    "./surface": {
+      "types": "./surface/surface.d.ts",
+      "import": "./surface/surface.js"
+    }
   },
   "files": [
     "design/index.mjs",
     "design/dtcg.mjs",
+    "design/dtcg.d.mts",
     "design/gate.mjs",
     "design/generate.mjs",
     "design/value-drift.mjs",
     "design/verify-pack.mjs",
-    "design/README.md"
+    "design/token-completeness.mjs",
+    "design/build-artefacts.mjs",
+    "design/README.md",
+    "surface/surface.js",
+    "surface/surface.d.ts"
   ],
   "scripts": {
-    "test": "node --test"
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
   }
 }