spec-layer 0.3.0 → 0.4.0

package/dist/cli.js

@@ -588,6 +588,71 @@ var STATE_ORDER = [
 ];
 var STATE_VOCAB = new Set(STATE_ORDER);
 
+// ../extractor/src/v5/precision.ts
+var SIGNIFICANT_DIGITS = 7;
+var FLOAT32_EXACT_LIMIT = 16777216;
+function canonicalNumber(n) {
+  if (!Number.isFinite(n)) return n;
+  if (Number.isInteger(n)) return n + 0;
+  if (Math.abs(n) >= FLOAT32_EXACT_LIMIT) return n + 0;
+  return Number(n.toPrecision(SIGNIFICANT_DIGITS)) + 0;
+}
+
+// ../extractor/src/v5/diagnostics.ts
+var DEFAULT_SEVERITY = {
+  UNRESOLVED_ALIAS: "error",
+  UNRESOLVED_EXTERNAL_ALIAS: "error",
+  ALIAS_CYCLE: "error",
+  ALIAS_TYPE_MISMATCH: "error",
+  MISSING_MODE_VALUE: "error",
+  DUPLICATE_SOURCE_ID: "error",
+  PATH_COLLISION: "error",
+  UNSUPPORTED_VALUE_TYPE: "error",
+  INCONSISTENT_VALUE_SHAPE: "error",
+  AMBIGUOUS_ALIAS_TARGET: "error",
+  INVALID_SOURCE_COLOR: "error",
+  // Error, and the same severity UNRESOLVED_ALIAS carries: §18 Level 2 makes
+  // no distinction between reference classes, and an artifact whose token
+  // points at a collection that is not there is broken in exactly the way a
+  // dangling alias is -- a consumer joining on the id gets nothing.
+  UNRESOLVED_REFERENCE: "error",
+  SOURCE_PARTIALLY_UNAVAILABLE: "error",
+  STYLE_BINDING_DRIFT: "warning",
+  CONFUSABLE_NAME: "warning",
+  INFERRED_LIFECYCLE: "warning",
+  DEPRECATED_REFERENCE: "warning",
+  GENERATED_NAME_COLLISION: "warning",
+  // Warning, not error: a migrated artifact with synthetic ids is still usable
+  // for generation -- what it cannot do is survive a rename, which is a fact
+  // about future diffs rather than about this artifact's correctness.
+  SYNTHETIC_IDENTITY: "warning",
+  // Warning, not error: the number is retained and usable, and Level 4
+  // readiness is a consumer's judgment. What the consumer must decide is the
+  // unit; the message says so and `units` overrides in the CLI are the
+  // remedy.
+  UNIT_METADATA_UNAVAILABLE: "warning",
+  MODE_VALUES_IDENTICAL: "info",
+  MISSING_DESCRIPTION: "info",
+  // Info, not error: no value depends on metadata the Plugin API never
+  // exposes in the first place -- there is nothing for a consumer to decide
+  // and nothing missing that this export could have captured.
+  METADATA_UNAVAILABLE: "info",
+  // Info, not error: a deliberately scoped export states its own scope in
+  // `completeness`; that is a fact about the request, not a defect in it.
+  EXPORT_SCOPED: "info"
+};
+var compareCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+function diagnostic(code, fields) {
+  return {
+    code,
+    severity: DEFAULT_SEVERITY[code],
+    entity_id: fields.entity_id,
+    ...fields.mode_id !== void 0 ? { mode_id: fields.mode_id } : {},
+    message: fields.message,
+    ...fields.details !== void 0 ? { details: fields.details } : {}
+  };
+}
+
 // ../extractor/src/hash.ts
 var import_js_sha256 = __toESM(require_sha256(), 1);
 
@@ -733,9 +798,1241 @@ var FOUNDATION_SYSTEM_PROMPT = [
   "No prose outside the JSON, no code fence."
 ].join("\n");
 
+// ../extractor/src/v5/value.ts
+var SUPPORTED_UNITS = ["px", "rem", "em", "%", "deg", "ms", "s"];
+var SUPPORTED_TOKEN_TYPES = [
+  "color",
+  "dimension",
+  "number",
+  "string",
+  "boolean",
+  "duration",
+  "cubic_bezier",
+  "font_family"
+];
+var SUPPORTED_VALUE_KINDS = ["literal", "alias", "missing"];
+var SUPPORTED_DURATION_UNITS = ["ms", "s"];
+
 // ../extractor/src/v5/canonical.ts
 var import_js_sha2562 = __toESM(require_sha256(), 1);
 
+// ../extractor/src/v5/validate.ts
+var ROOT = "<artifact>";
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isNonEmptyString = (v) => typeof v === "string" && v.length > 0;
+var isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === "string");
+var HEX_RE = /^#[0-9a-f]{6}$/;
+function shape(entityId, message, modeId) {
+  return diagnostic("INCONSISTENT_VALUE_SHAPE", {
+    entity_id: entityId,
+    message,
+    ...modeId !== void 0 ? { mode_id: modeId } : {}
+  });
+}
+function unsupported(entityId, message, modeId) {
+  return diagnostic("UNSUPPORTED_VALUE_TYPE", {
+    entity_id: entityId,
+    message,
+    ...modeId !== void 0 ? { mode_id: modeId } : {}
+  });
+}
+function validateTypedValue(type, tv, entityId, out, modeId) {
+  switch (type) {
+    case "color": {
+      if (tv.color_space !== "srgb") {
+        out.push(unsupported(entityId, 'color.color_space must be "srgb".', modeId));
+      }
+      if (typeof tv.hex !== "string" || !HEX_RE.test(tv.hex)) {
+        out.push(unsupported(entityId, 'color.hex must be six lowercase hex digits with a leading "#".', modeId));
+      }
+      if (!isFiniteNumber(tv.alpha) || tv.alpha < 0 || tv.alpha > 1) {
+        out.push(unsupported(entityId, "color.alpha must be a finite number between 0 and 1.", modeId));
+      }
+      if (tv.channels !== void 0) {
+        const channels = tv.channels;
+        if (!Array.isArray(channels) || channels.length !== 3 || !channels.every(isFiniteNumber)) {
+          out.push(unsupported(entityId, "color.channels must be three finite numbers when present.", modeId));
+        }
+      }
+      break;
+    }
+    case "dimension": {
+      if (!isFiniteNumber(tv.number)) {
+        out.push(unsupported(entityId, "dimension.number must be a finite number.", modeId));
+      }
+      if (typeof tv.unit !== "string" || !SUPPORTED_UNITS.includes(tv.unit)) {
+        out.push(unsupported(entityId, "dimension.unit is missing or outside the supported unit vocabulary.", modeId));
+      }
+      break;
+    }
+    case "number": {
+      if (!isFiniteNumber(tv.value)) {
+        out.push(unsupported(entityId, "number.value must be a finite number.", modeId));
+      }
+      break;
+    }
+    case "string": {
+      if (typeof tv.value !== "string") {
+        out.push(unsupported(entityId, "string.value must be a string.", modeId));
+      }
+      break;
+    }
+    case "boolean": {
+      if (typeof tv.value !== "boolean") {
+        out.push(unsupported(entityId, "boolean.value must be a boolean.", modeId));
+      }
+      break;
+    }
+    case "duration": {
+      if (!isFiniteNumber(tv.number)) {
+        out.push(unsupported(entityId, "duration.number must be a finite number.", modeId));
+      }
+      if (typeof tv.unit !== "string" || !SUPPORTED_DURATION_UNITS.includes(tv.unit)) {
+        out.push(unsupported(entityId, 'duration.unit must be "ms" or "s".', modeId));
+      }
+      break;
+    }
+    case "cubic_bezier": {
+      const value = tv.value;
+      if (!Array.isArray(value) || value.length !== 4 || !value.every(isFiniteNumber)) {
+        out.push(unsupported(entityId, "cubic_bezier.value must be four finite numbers.", modeId));
+      }
+      break;
+    }
+    case "font_family": {
+      if (typeof tv.value !== "string") {
+        out.push(unsupported(entityId, "font_family.value must be a string.", modeId));
+      }
+      break;
+    }
+    default:
+      break;
+  }
+}
+function validateTypedValueEnvelope(value, entityId, out, modeId, expectedType) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "A typed value must be an object.", modeId));
+    return;
+  }
+  const { type } = value;
+  if (typeof type !== "string" || !SUPPORTED_TOKEN_TYPES.includes(type)) {
+    out.push(shape(entityId, `Typed value has an unrecognized or missing "type" discriminant: ${JSON.stringify(type)}.`, modeId));
+    return;
+  }
+  if (expectedType !== void 0 && type !== expectedType) {
+    out.push(shape(
+      entityId,
+      `Expected a "${expectedType}" typed value, but the value declares "${type}".`,
+      modeId
+    ));
+  }
+  validateTypedValue(type, value, entityId, out, modeId);
+}
+function validateChainStep(step, entityId, out, modeId) {
+  if (!isRecord(step) || typeof step.token_id !== "string" || typeof step.mode_id !== "string") {
+    out.push(shape(entityId, "A resolution chain step must carry both token_id and mode_id.", modeId));
+  }
+}
+function validateAliasReference(ref, entityId, out, modeId) {
+  if (!(ref.target_id === null || typeof ref.target_id === "string")) {
+    out.push(shape(entityId, "alias.reference.target_id must be a string or null.", modeId));
+  }
+  if (!(ref.target_collection_id === null || typeof ref.target_collection_id === "string")) {
+    out.push(shape(entityId, "alias.reference.target_collection_id must be a string or null.", modeId));
+  }
+  if (!isStringArray(ref.target_path)) {
+    out.push(shape(entityId, "alias.reference.target_path must be an array of strings.", modeId));
+  }
+  if (typeof ref.external !== "boolean") {
+    out.push(shape(entityId, "alias.reference.external must be a boolean.", modeId));
+  }
+  if (ref.source_library_name !== void 0 && typeof ref.source_library_name !== "string") {
+    out.push(shape(entityId, "alias.reference.source_library_name must be a string when present.", modeId));
+  }
+}
+function validateAliasResolution(resolved2, entityId, out, modeId, expectedType) {
+  const { status } = resolved2;
+  if (status === "resolved") {
+    validateTypedValueEnvelope(resolved2.value, entityId, out, modeId, expectedType);
+  } else if (status === "unresolved") {
+    if (!isNonEmptyString(resolved2.reason)) {
+      out.push(shape(entityId, "An unresolved alias must carry a non-empty reason.", modeId));
+    }
+    if (resolved2.value !== null) {
+      out.push(shape(entityId, "An unresolved alias must carry a null value.", modeId));
+    }
+  } else {
+    out.push(shape(entityId, `alias.resolved.status has an unrecognized value: ${JSON.stringify(status)}.`, modeId));
+  }
+  if (!Array.isArray(resolved2.chain)) {
+    out.push(shape(entityId, "alias.resolved.chain must be an array.", modeId));
+  } else {
+    for (const step of resolved2.chain) validateChainStep(step, entityId, out, modeId);
+  }
+}
+function validateValue(value, entityId, modeId, out, expectedType) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "A token value must be an object, not a bare primitive.", modeId));
+    return;
+  }
+  const { kind } = value;
+  if (typeof kind !== "string" || !SUPPORTED_VALUE_KINDS.includes(kind)) {
+    out.push(shape(entityId, `Value has an unrecognized or missing "kind" discriminant: ${JSON.stringify(kind)}.`, modeId));
+    return;
+  }
+  if (kind === "literal") {
+    validateTypedValueEnvelope(value.value, entityId, out, modeId, expectedType);
+  } else if (kind === "alias") {
+    if (!isRecord(value.reference)) {
+      out.push(shape(entityId, "An alias value must carry a reference object.", modeId));
+    } else {
+      validateAliasReference(value.reference, entityId, out, modeId);
+    }
+    if (!isRecord(value.resolved)) {
+      out.push(shape(entityId, "An alias value must carry a resolved object.", modeId));
+    } else {
+      validateAliasResolution(value.resolved, entityId, out, modeId, expectedType);
+    }
+  } else if (kind === "missing") {
+    if (!isNonEmptyString(value.reason)) {
+      out.push(shape(entityId, "A missing value must carry a non-empty reason.", modeId));
+    }
+  }
+}
+function validateIdentity(entity, entityId, kind, out) {
+  if (!isNonEmptyString(entity.id)) {
+    out.push(shape(entityId, `${kind}.id must be a non-empty string.`));
+  }
+  if (typeof entity.name !== "string") {
+    out.push(shape(entityId, `${kind}.name must be a string.`));
+  }
+  if (!isStringArray(entity.path) || entity.path.length === 0) {
+    out.push(shape(entityId, `${kind}.path must be a non-empty array of strings.`));
+  }
+  if (entity.suggested_code_name !== void 0 && typeof entity.suggested_code_name !== "string") {
+    out.push(shape(entityId, `${kind}.suggested_code_name must be a string when present.`));
+  }
+}
+function validatePublication(value, entityId, out) {
+  if (!isRecord(value) || typeof value.published !== "boolean" || typeof value.hidden_from_publishing !== "boolean") {
+    out.push(shape(
+      entityId,
+      "publication must state boolean published and hidden_from_publishing fields."
+    ));
+  }
+}
+function validateLifecycle(value, entityId, out) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "lifecycle must be an object when present."));
+    return;
+  }
+  if (!["active", "deprecated", "archived"].includes(value.status)) {
+    out.push(shape(entityId, "lifecycle.status must be active, deprecated, or archived."));
+  }
+  if (!(value.replacement_id === null || typeof value.replacement_id === "string")) {
+    out.push(shape(entityId, "lifecycle.replacement_id must be a string or null."));
+  }
+}
+function validateSource(value, entityId, out) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "source must be an object when present."));
+    return;
+  }
+  if (typeof value.remote !== "boolean") {
+    out.push(shape(entityId, "source.remote must be a boolean."));
+  }
+  for (const field of ["library_file_id", "library_name", "modified_at"]) {
+    if (!(value[field] === null || typeof value[field] === "string")) {
+      out.push(shape(entityId, `source.${field} must be a string or null.`));
+    }
+  }
+}
+function validateOptionalEntityMetadata(entity, entityId, out, includeSource = false, includeLifecycle = true) {
+  if (entity.publication !== void 0) validatePublication(entity.publication, entityId, out);
+  if (includeLifecycle && entity.lifecycle !== void 0) validateLifecycle(entity.lifecycle, entityId, out);
+  if (includeSource && entity.source !== void 0) validateSource(entity.source, entityId, out);
+}
+function validateCollection(collection, index, out) {
+  if (!isRecord(collection)) {
+    out.push(shape(`collections[${index}]`, "A collection must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(collection.id) ? collection.id : `collections[${index}]`;
+  validateIdentity(collection, entityId, "collection", out);
+  if (!isNonEmptyString(collection.default_mode_id)) {
+    out.push(shape(entityId, "collection.default_mode_id must be a non-empty string."));
+  }
+  if (!Array.isArray(collection.modes)) {
+    out.push(shape(entityId, "collection.modes must be an array."));
+  } else {
+    collection.modes.forEach((mode, modeIndex) => {
+      if (!isRecord(mode)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}] must be an object.`));
+        return;
+      }
+      if (!isNonEmptyString(mode.id)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].id must be a non-empty string.`));
+      }
+      if (typeof mode.name !== "string") {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].name must be a string.`));
+      }
+      if (!isFiniteNumber(mode.order)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].order must be a finite number.`));
+      }
+    });
+  }
+  validateOptionalEntityMetadata(collection, entityId, out, true, false);
+}
+function validateToken(token, index, out) {
+  if (!isRecord(token)) {
+    out.push(shape(`tokens[${index}]`, "A token must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(token.id) ? token.id : `tokens[${index}]`;
+  if (!isNonEmptyString(token.id)) {
+    out.push(shape(entityId, "token.id must be a non-empty string."));
+  }
+  if (typeof token.collection_id !== "string" || token.collection_id.length === 0) {
+    out.push(shape(entityId, "token.collection_id must be a non-empty string."));
+  }
+  if (typeof token.name !== "string") {
+    out.push(shape(entityId, "token.name must be a string."));
+  }
+  if (!isStringArray(token.path) || token.path.length === 0) {
+    out.push(shape(entityId, "token.path must be a non-empty array of strings."));
+  }
+  if (token.suggested_code_name !== void 0 && typeof token.suggested_code_name !== "string") {
+    out.push(shape(entityId, "token.suggested_code_name must be a string when present."));
+  }
+  if (token.code_syntax !== void 0) {
+    if (!isRecord(token.code_syntax) || Object.values(token.code_syntax).some((v) => typeof v !== "string")) {
+      out.push(shape(entityId, "token.code_syntax must be an object of strings when present."));
+    }
+  }
+  let tokenType;
+  if (typeof token.type !== "string") {
+    out.push(shape(entityId, "token.type must be a string."));
+  } else if (!SUPPORTED_TOKEN_TYPES.includes(token.type)) {
+    out.push(shape(entityId, `token.type is not a recognized token type: ${JSON.stringify(token.type)}.`));
+  } else {
+    tokenType = token.type;
+  }
+  if (typeof token.description !== "string") {
+    out.push(shape(entityId, "token.description must be present and a string (an empty string is allowed)."));
+  }
+  if (!isStringArray(token.scopes)) {
+    out.push(shape(entityId, "token.scopes must be an array of strings."));
+  }
+  validateOptionalEntityMetadata(token, entityId, out);
+  if (!isRecord(token.values)) {
+    out.push(shape(entityId, "token.values must be an object keyed by mode id."));
+    return;
+  }
+  for (const [modeId, value] of Object.entries(token.values)) {
+    validateValue(value, entityId, modeId, out, tokenType);
+  }
+}
+function validateStyleProperty(property, entityId, propertyName, out) {
+  if (!isRecord(property)) {
+    out.push(shape(entityId, `typography.properties.${propertyName} must be an object.`));
+    return;
+  }
+  const { source } = property;
+  if (!isRecord(source)) {
+    out.push(shape(entityId, `typography.properties.${propertyName}.source must be an object.`));
+  } else if (source.kind === "alias") {
+    if (!(source.target_id === null || typeof source.target_id === "string")) {
+      out.push(shape(entityId, `typography.properties.${propertyName}.source.target_id must be a string or null.`));
+    }
+    if (!isStringArray(source.target_path)) {
+      out.push(shape(entityId, `typography.properties.${propertyName}.source.target_path must be an array of strings.`));
+    }
+  } else if (source.kind !== "literal") {
+    out.push(shape(entityId, `typography.properties.${propertyName}.source.kind must be literal or alias.`));
+  }
+  if (property.resolved !== null) {
+    validateTypedValueEnvelope(property.resolved, entityId, out);
+  }
+}
+var TYPOGRAPHY_STYLE_PROPERTIES = [
+  "font_family",
+  "font_weight",
+  "font_size",
+  "line_height",
+  "letter_spacing",
+  "paragraph_spacing",
+  "paragraph_indent"
+];
+function validateTypographyStyle(style, index, out) {
+  if (!isRecord(style)) {
+    out.push(shape(`styles.typography[${index}]`, "A typography style must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(style.id) ? style.id : `styles.typography[${index}]`;
+  validateIdentity(style, entityId, "typography style", out);
+  if (typeof style.description !== "string") {
+    out.push(shape(entityId, "typography.description must be a string."));
+  }
+  if (!isRecord(style.properties)) {
+    out.push(shape(entityId, "typography.properties must be an object."));
+  } else {
+    for (const propertyName of TYPOGRAPHY_STYLE_PROPERTIES) {
+      validateStyleProperty(style.properties[propertyName], entityId, propertyName, out);
+    }
+    if (typeof style.properties.text_case !== "string") {
+      out.push(shape(entityId, "typography.properties.text_case must be a string."));
+    }
+    if (typeof style.properties.text_decoration !== "string") {
+      out.push(shape(entityId, "typography.properties.text_decoration must be a string."));
+    }
+  }
+  validateOptionalEntityMetadata(style, entityId, out, true);
+}
+var EFFECT_KINDS = ["drop_shadow", "inner_shadow", "layer_blur", "background_blur"];
+function validateEffect(effect, entityId, index, out) {
+  if (!isRecord(effect)) {
+    out.push(shape(entityId, `effects[${index}] must be an object.`));
+    return;
+  }
+  if (!EFFECT_KINDS.includes(effect.type)) {
+    out.push(shape(entityId, `effects[${index}].type is not a recognized effect kind.`));
+  }
+  if (typeof effect.visible !== "boolean") {
+    out.push(shape(entityId, `effects[${index}].visible must be a boolean.`));
+  }
+  if (effect.blend_mode !== void 0 && typeof effect.blend_mode !== "string") {
+    out.push(shape(entityId, `effects[${index}].blend_mode must be a string when present.`));
+  }
+  if (effect.color !== void 0) {
+    validateTypedValueEnvelope(effect.color, entityId, out, void 0, "color");
+  }
+  for (const field of ["offset_x", "offset_y", "blur", "spread"]) {
+    if (effect[field] !== void 0) {
+      validateTypedValueEnvelope(effect[field], entityId, out, void 0, "dimension");
+    }
+  }
+  if (effect.show_behind_node !== void 0 && typeof effect.show_behind_node !== "boolean") {
+    out.push(shape(entityId, `effects[${index}].show_behind_node must be a boolean when present.`));
+  }
+}
+function validateEffectStyle(style, index, out) {
+  if (!isRecord(style)) {
+    out.push(shape(`styles.effects[${index}]`, "An effect style must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(style.id) ? style.id : `styles.effects[${index}]`;
+  validateIdentity(style, entityId, "effect style", out);
+  if (!(style.mode_id === null || typeof style.mode_id === "string")) {
+    out.push(shape(entityId, "effect style.mode_id must be a string or null."));
+  }
+  if (!Array.isArray(style.effects)) {
+    out.push(shape(entityId, "effect style.effects must be an array."));
+  } else {
+    style.effects.forEach((effect, effectIndex) => validateEffect(effect, entityId, effectIndex, out));
+  }
+  if (style.bindings !== void 0) {
+    if (!Array.isArray(style.bindings)) {
+      out.push(shape(entityId, "effect style.bindings must be an array when present."));
+    } else {
+      style.bindings.forEach((binding, bindingIndex) => {
+        if (!isRecord(binding) || !isNonEmptyString(binding.property) || !isNonEmptyString(binding.token_id)) {
+          out.push(shape(
+            entityId,
+            `effect style.bindings[${bindingIndex}] must carry non-empty property and token_id strings.`
+          ));
+        }
+      });
+    }
+  }
+  validateOptionalEntityMetadata(style, entityId, out, true);
+}
+var COMPLETENESS_VALUES = ["complete", "partial", "unavailable"];
+function validateRootSections(artifact, out) {
+  if (!isRecord(artifact.spec_layer)) {
+    out.push(shape(ROOT, "`spec_layer` must be an object."));
+  }
+  const completeness = artifact.completeness;
+  if (!isRecord(completeness) || !COMPLETENESS_VALUES.includes(completeness.collections) || !COMPLETENESS_VALUES.includes(completeness.styles) || !isStringArray(completeness.unavailable_sources)) {
+    out.push(shape(ROOT, "`completeness` must state collections/styles completeness and list unavailable sources."));
+  }
+  if (!Array.isArray(artifact.collections)) {
+    out.push(shape(ROOT, "`collections` must be an array."));
+  } else {
+    artifact.collections.forEach((collection, index) => validateCollection(collection, index, out));
+  }
+  if (!isRecord(artifact.styles) || !Array.isArray(artifact.styles.typography) || !Array.isArray(artifact.styles.effects)) {
+    out.push(shape(ROOT, "`styles` must be an object with `typography` and `effects` arrays."));
+  } else {
+    artifact.styles.typography.forEach((style, index) => validateTypographyStyle(style, index, out));
+    artifact.styles.effects.forEach((style, index) => validateEffectStyle(style, index, out));
+  }
+  if (!Array.isArray(artifact.diagnostics)) {
+    out.push(shape(ROOT, "`diagnostics` must be an array."));
+  }
+  if (!isRecord(artifact.statistics)) {
+    out.push(shape(ROOT, "`statistics` must be an object."));
+  }
+  if (artifact.guidelines !== void 0) {
+    const guidelines = artifact.guidelines;
+    if (!isRecord(guidelines) || guidelines.origin !== "generated" || !isRecord(guidelines.group_descriptions)) {
+      out.push(shape(
+        ROOT,
+        '`guidelines` must state origin "generated" and a group_descriptions object.'
+      ));
+    } else {
+      for (const [collectionName, folders] of Object.entries(guidelines.group_descriptions)) {
+        if (!isRecord(folders) || Object.values(folders).some((description) => typeof description !== "string")) {
+          out.push(shape(
+            ROOT,
+            `guidelines.group_descriptions[${JSON.stringify(collectionName)}] must map folder names to strings.`
+          ));
+        }
+      }
+    }
+  }
+}
+function validateLevel1(artifact) {
+  try {
+    const out = [];
+    if (!isRecord(artifact)) {
+      out.push(shape(ROOT, "The artifact root must be an object."));
+      return out;
+    }
+    validateRootSections(artifact, out);
+    if (!Array.isArray(artifact.tokens)) {
+      out.push(shape(ROOT, "`tokens` must be an array."));
+    } else {
+      artifact.tokens.forEach((token, index) => validateToken(token, index, out));
+    }
+    return out;
+  } catch (err) {
+    const message = err instanceof Error && err.message ? `The artifact could not be read; accessing its properties threw: ${err.message}` : "The artifact could not be read; accessing its properties threw.";
+    return [diagnostic("INCONSISTENT_VALUE_SHAPE", {
+      entity_id: "artifact",
+      message
+    })];
+  }
+}
+
+// ../extractor/src/v5/dtcg.ts
+function dtcgSegments(name) {
+  const segments = [];
+  const notes = [];
+  for (const raw of name.split("/")) {
+    const parts = raw.includes(".") ? raw.split(".") : [raw];
+    if (parts.length > 1) notes.push({ code: "segment_split", original: raw });
+    for (const part of parts) {
+      let out = part;
+      if (out === "") out = "_";
+      if (/[{}]/.test(out)) out = out.replace(/[{}]/g, "_");
+      if (out.startsWith("$")) out = `_${out}`;
+      if (out !== part) notes.push({ code: "name_escaped", original: part });
+      segments.push(out);
+    }
+  }
+  return { segments, notes };
+}
+var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
+var RESERVED_FILE_NAMES = [
+  "styles.typography.json",
+  "styles.effects.json",
+  "resolver.json",
+  "spec-layer.meta.json",
+  "report.json"
+];
+function fileNameFor(collection, mode, taken) {
+  const base = `${slug(collection.name)}.${slug(mode.name)}`;
+  let candidate = `${base}.json`;
+  let n = 1;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `${base}-${n}.json`;
+  }
+  taken.add(candidate);
+  return candidate;
+}
+function hexByte(n) {
+  return Math.round(n * 255).toString(16).padStart(2, "0");
+}
+function colorComponents(color) {
+  if (color.channels) return [color.channels[0], color.channels[1], color.channels[2]];
+  const at = (i) => canonicalNumber(parseInt(color.hex.slice(i, i + 2), 16) / 255);
+  return [at(1), at(3), at(5)];
+}
+function dtcgLiteral(value, scopes, style) {
+  switch (value.type) {
+    case "color": {
+      if (style === "legacy") {
+        const alpha = value.alpha === 1 ? "" : hexByte(value.alpha);
+        return { $type: "color", $value: `${value.hex}${alpha}` };
+      }
+      return {
+        $type: "color",
+        $value: {
+          colorSpace: "srgb",
+          components: colorComponents(value),
+          alpha: value.alpha,
+          hex: value.hex
+        }
+      };
+    }
+    case "dimension": {
+      if (value.unit !== "px" && value.unit !== "rem") {
+        return { omit: "unit_not_expressible", details: { unit: value.unit, number: value.number } };
+      }
+      return {
+        $type: "dimension",
+        $value: style === "legacy" ? `${value.number}${value.unit}` : { value: value.number, unit: value.unit }
+      };
+    }
+    case "duration":
+      return {
+        $type: "duration",
+        $value: style === "legacy" ? `${value.number}${value.unit}` : { value: value.number, unit: value.unit }
+      };
+    case "number":
+      return { $type: scopes.includes("FONT_WEIGHT") ? "fontWeight" : "number", $value: value.value };
+    case "cubic_bezier":
+      return { $type: "cubicBezier", $value: [...value.value] };
+    case "font_family":
+      return { $type: "fontFamily", $value: value.value };
+    case "string":
+    case "boolean":
+      return { omit: "type_not_expressible", details: { type: value.type } };
+    default: {
+      const exhaustive = value;
+      return exhaustive;
+    }
+  }
+}
+function setLeaf(tree, segments, leaf) {
+  let node = tree;
+  for (const seg of segments.slice(0, -1)) {
+    const next = node[seg];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) node[seg] = {};
+    node = node[seg];
+  }
+  node[segments[segments.length - 1]] = leaf;
+}
+var KEY_ORDER = ["$type", "$value", "$description", "$deprecated", "$extensions"];
+function sortTree(value) {
+  if (Array.isArray(value)) return value.map(sortTree);
+  if (typeof value !== "object" || value === null) return value;
+  const rank = (k) => {
+    const i = KEY_ORDER.indexOf(k);
+    return i === -1 ? KEY_ORDER.length : i;
+  };
+  const keys = Object.keys(value).sort((a, b) => rank(a) - rank(b) || compareCodeUnits(a, b));
+  return Object.fromEntries(keys.map((k) => [k, sortTree(value[k])]));
+}
+function reportOnce(p, entry2) {
+  const key = JSON.stringify([entry2.code, entry2.path, entry2.mode ?? null, entry2.details]);
+  if (p.reportKeys.has(key)) return;
+  p.reportKeys.add(key);
+  p.report.push(entry2);
+}
+function indexPaths(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const token of p.artifact.tokens) {
+    const collection = p.collectionById.get(token.collection_id);
+    if (!collection) continue;
+    const head = dtcgSegments(collection.name);
+    const tail = dtcgSegments(token.name);
+    const segments = [...head.segments, ...tail.segments];
+    const path = segments.join(".");
+    p.segmentsById.set(token.id, segments);
+    for (const note of [...head.notes, ...tail.notes]) {
+      reportOnce(p, {
+        code: note.code,
+        severity: note.code === "segment_split" ? "info" : "warning",
+        path,
+        message: note.code === "segment_split" ? `The segment "${note.original}" contains "." and was split into nested groups.` : `The segment "${note.original}" contains a character DTCG forbids and was escaped.`,
+        details: { id: token.id, original: note.original }
+      });
+    }
+    owners.set(path, [...owners.get(path) ?? [], token]);
+  }
+  for (const [path, tokens] of owners) {
+    if (tokens.length === 1) {
+      p.pathById.set(tokens[0].id, path);
+      continue;
+    }
+    for (const token of tokens) {
+      p.omittedIds.add(token.id);
+      p.collidedIds.add(token.id);
+      reportOnce(p, {
+        code: "path_collision",
+        severity: "error",
+        path,
+        message: `${tokens.length} tokens share this DTCG path after escaping; all were omitted.`,
+        details: { id: token.id, ids: tokens.map((t) => t.id) }
+      });
+    }
+  }
+}
+function modeName(collection, modeId) {
+  return collection.modes.find((m) => m.id === modeId)?.name ?? modeId;
+}
+function unitOverrideFor(p, token, collection) {
+  const units = p.options.units;
+  if (!units) return void 0;
+  for (const key of Object.keys(units).sort(compareCodeUnits)) {
+    const slash = key.indexOf("/");
+    if (slash === -1 || key.slice(0, slash) !== collection.name) continue;
+    const glob = key.slice(slash + 1);
+    const escaped = glob.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+    if (new RegExp(`^${escaped}$`).test(token.name)) return units[key];
+  }
+  return void 0;
+}
+var STATED_NUMBER_SCOPES = ["FONT_WEIGHT", "OPACITY"];
+function projectedLiteral(p, token, resolved2, onOverrideConflict) {
+  const collection = p.collectionById.get(token.collection_id);
+  const override = collection ? unitOverrideFor(p, token, collection) : void 0;
+  let literal = resolved2;
+  if (override !== void 0 && literal.type === "number") {
+    if (token.scopes.some((s) => STATED_NUMBER_SCOPES.includes(s))) onOverrideConflict?.(override);
+    else literal = { type: "dimension", number: literal.value, unit: override };
+  }
+  return dtcgLiteral(literal, token.scopes, p.options.values);
+}
+function aliasLeafType(p, token, chain, resolved2) {
+  const terminal = chain.length > 0 ? p.tokenById.get(chain[chain.length - 1].token_id) : void 0;
+  return projectedLiteral(p, terminal ?? token, resolved2);
+}
+function modeLabels(collection) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const m of collection.modes) counts.set(m.name, (counts.get(m.name) ?? 0) + 1);
+  return new Map(collection.modes.map((m) => [m.id, counts.get(m.name) === 1 ? m.name : `${m.name} [${m.id}]`]));
+}
+function collectionLabels(collections) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const c of collections) counts.set(c.name, (counts.get(c.name) ?? 0) + 1);
+  return new Map(collections.map(
+    (c) => [c.id, counts.get(c.name) === 1 ? c.name : `${c.name} [${c.id}]`]
+  ));
+}
+function modeLabelOf(p, collection, modeId) {
+  return p.modeLabelsById.get(collection.id)?.get(modeId) ?? modeId;
+}
+var collectionLabelOf = (p, collection) => p.collectionLabelById.get(collection.id) ?? collection.name;
+function reportCollectionNameCollisions(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const collection of p.artifact.collections) {
+    owners.set(collection.name, [...owners.get(collection.name) ?? [], collection]);
+  }
+  for (const [name, collections] of owners) {
+    if (collections.length < 2) continue;
+    for (const collection of collections) {
+      reportOnce(p, {
+        code: "collection_name_collision",
+        severity: "warning",
+        path: collectionLabelOf(p, collection),
+        message: `${collections.length} collections are named "${name}"; the resolver labels each one by its id.`,
+        details: { id: collection.id, ids: collections.map((c) => c.id) }
+      });
+    }
+  }
+}
+function asJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function metaEntry(p, token, collection) {
+  const labels = p.modeLabelsById.get(collection.id) ?? modeLabels(collection);
+  const omitted = p.omittedIds.has(token.id);
+  const plain = (v) => {
+    if (v.kind === "literal" && (v.value.type === "boolean" || v.value.type === "string" || v.value.type === "number" || v.value.type === "font_family")) return v.value.value;
+    return asJson(v);
+  };
+  return {
+    id: token.id,
+    collection_id: token.collection_id,
+    type: token.type,
+    scopes: [...token.scopes],
+    ...token.code_syntax ? { code_syntax: token.code_syntax } : {},
+    ...token.publication ? { publication: token.publication } : {},
+    ...omitted ? {
+      omitted: true,
+      values: Object.fromEntries(Object.entries(token.values).map(([modeId, v]) => [labels.get(modeId) ?? modeId, plain(v)]))
+    } : {}
+  };
+}
+function reportDuplicateCodeSyntax(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const token of p.artifact.tokens) {
+    for (const [platform, identifier] of Object.entries(token.code_syntax ?? {})) {
+      const key = JSON.stringify([platform, identifier]);
+      owners.set(key, [...owners.get(key) ?? [], token]);
+    }
+  }
+  for (const [key, tokens] of owners) {
+    if (tokens.length < 2) continue;
+    const [platform, identifier] = JSON.parse(key);
+    for (const token of tokens) {
+      reportOnce(p, {
+        code: "duplicate_code_syntax",
+        severity: "warning",
+        path: p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name,
+        message: `${tokens.length} tokens declare the ${platform} identifier "${identifier}".`,
+        details: { id: token.id, platform, identifier, ids: tokens.map((t) => t.id) }
+      });
+    }
+  }
+}
+var SPEC_LAYER_EXT = "com.spec-layer";
+function reportBindingDropped(p, path, property, targetId) {
+  reportOnce(p, {
+    code: "binding_dropped",
+    severity: "warning",
+    path,
+    message: `The ${property} property is bound to a token this export does not carry; the resolved literal is written instead.`,
+    details: {
+      property,
+      target_id: targetId,
+      reason: p.tokenIds.has(targetId) ? "target_omitted" : "target_unavailable"
+    }
+  });
+}
+function styleMember(p, property, scopes, path, name) {
+  if (property.source.kind === "alias" && property.source.target_id !== null) {
+    const targetId = property.source.target_id;
+    const target = p.omittedIds.has(targetId) ? void 0 : p.pathById.get(targetId);
+    if (target !== void 0) return { value: `{${target}}` };
+    reportBindingDropped(p, path, name, targetId);
+  }
+  if (property.resolved === null) {
+    reportOnce(p, {
+      code: "value_omitted",
+      severity: "warning",
+      path,
+      message: `The ${name} property has no resolved value and was omitted.`,
+      details: { property: name, reason: "source_unavailable" }
+    });
+    return null;
+  }
+  const converted = dtcgLiteral(property.resolved, scopes, p.options.values);
+  if ("omit" in converted) {
+    if (converted.omit === "unit_not_expressible") {
+      reportOnce(p, {
+        code: "unit_not_expressible",
+        severity: "info",
+        path,
+        message: `The ${name} unit is not a DTCG dimension unit; the value is kept under $extensions.`,
+        details: { property: name, ...converted.details }
+      });
+      const d = property.resolved;
+      return { extension: { value: d.number, unit: d.unit } };
+    }
+    reportOnce(p, {
+      code: "type_not_expressible",
+      severity: "warning",
+      path,
+      message: `The ${name} property has a type DTCG cannot state and was omitted.`,
+      details: { property: name, ...converted.details }
+    });
+    return null;
+  }
+  return { value: converted.$value };
+}
+var TYPOGRAPHY_MEMBERS = [
+  ["font_family", "fontFamily", []],
+  ["font_size", "fontSize", []],
+  ["font_weight", "fontWeight", ["FONT_WEIGHT"]],
+  ["line_height", "lineHeight", []],
+  ["letter_spacing", "letterSpacing", []]
+];
+var TYPOGRAPHY_EXTENSION_MEMBERS = [
+  ["paragraph_spacing", "paragraphSpacing"],
+  ["paragraph_indent", "paragraphIndent"]
+];
+function typographyLeaf(p, style, path) {
+  const value = {};
+  const ext = {};
+  for (const [key, name, scopes] of TYPOGRAPHY_MEMBERS) {
+    const property = style.properties[key];
+    if (key === "line_height" && property.resolved?.type === "dimension") {
+      const boundTo = property.source.kind === "alias" ? property.source.target_id : null;
+      let targetExported = false;
+      if (property.resolved.unit === "%" && boundTo !== null) {
+        targetExported = !p.omittedIds.has(boundTo) && p.pathById.get(boundTo) !== void 0;
+        if (!targetExported) reportBindingDropped(p, path, name, boundTo);
+      }
+      if (property.resolved.unit === "%" && !targetExported) {
+        value[name] = canonicalNumber(property.resolved.number / 100);
+        continue;
+      }
+      reportOnce(p, {
+        code: "unit_not_expressible",
+        severity: "info",
+        path,
+        message: "DTCG line height is a unitless multiplier of the font size; the measured value is kept under $extensions.",
+        // The binding is replaced by a literal here, so the entry names the
+        // target it stood for; without it a consumer cannot tell this value
+        // was bound at all.
+        details: {
+          property: name,
+          unit: property.resolved.unit,
+          number: property.resolved.number,
+          ...boundTo !== null ? { target_id: boundTo } : {}
+        }
+      });
+      ext[name] = { value: property.resolved.number, unit: property.resolved.unit };
+      continue;
+    }
+    const member = styleMember(p, property, scopes, path, name);
+    if (member === null) continue;
+    if ("value" in member) value[name] = member.value;
+    else ext[name] = member.extension;
+  }
+  for (const [key, name] of TYPOGRAPHY_EXTENSION_MEMBERS) {
+    const member = styleMember(p, style.properties[key], [], path, name);
+    if (member === null) continue;
+    ext[name] = "value" in member ? member.value : member.extension;
+  }
+  ext.textCase = style.properties.text_case;
+  ext.textDecoration = style.properties.text_decoration;
+  return {
+    $type: "typography",
+    $value: value,
+    ...style.description.length > 0 ? { $description: style.description } : {},
+    $extensions: { [SPEC_LAYER_EXT]: ext }
+  };
+}
+var SHADOW_FIELDS = [
+  ["color", "color"],
+  ["offset_x", "offsetX"],
+  ["offset_y", "offsetY"],
+  ["blur", "blur"],
+  ["spread", "spread"]
+];
+function effectLeaf(p, style, path) {
+  const bindings = new Map((style.bindings ?? []).map((b) => [b.property, b.token_id]));
+  const shadows = [];
+  const layers = [];
+  style.effects.forEach((effect, index) => {
+    const isShadow = effect.type === "drop_shadow" || effect.type === "inner_shadow";
+    const layer = { index, type: effect.type, visible: effect.visible };
+    if (effect.blend_mode !== void 0) layer.blend_mode = effect.blend_mode;
+    if (!isShadow && effect.blur) {
+      const b = dtcgLiteral(effect.blur, [], p.options.values);
+      if (!("omit" in b)) layer.blur = b.$value;
+    }
+    layers.push(layer);
+    if (!isShadow || !effect.visible) return;
+    const shadow = {};
+    for (const [field, name] of SHADOW_FIELDS) {
+      const boundId = bindings.get(`effects[${index}].${field}`);
+      const boundPath = boundId !== void 0 && !p.omittedIds.has(boundId) ? p.pathById.get(boundId) : void 0;
+      if (boundPath !== void 0) {
+        shadow[name] = `{${boundPath}}`;
+        continue;
+      }
+      if (boundId !== void 0) {
+        reportBindingDropped(p, path, `effects[${index}].${field}`, boundId);
+      }
+      const raw = effect[field];
+      if (raw === void 0) continue;
+      const converted = dtcgLiteral(raw, [], p.options.values);
+      if (!("omit" in converted)) shadow[name] = converted.$value;
+    }
+    shadow.inset = effect.type === "inner_shadow";
+    shadows.push(shadow);
+  });
+  if (shadows.length === 0) {
+    reportOnce(p, {
+      code: "effect_not_expressible",
+      severity: "warning",
+      path,
+      message: "The style has no visible shadow; DTCG has no blur type, so it is kept only under $extensions.",
+      details: { id: style.id }
+    });
+  }
+  return {
+    $type: "shadow",
+    $value: shadows,
+    $extensions: { [SPEC_LAYER_EXT]: { layers } }
+  };
+}
+function styleFiles(p) {
+  const files = {};
+  const build = (styles, root, file, leafOf) => {
+    if (styles.length === 0) return;
+    const tree = {};
+    const seen = /* @__PURE__ */ new Map();
+    for (const style of styles) {
+      const segments = [root, ...dtcgSegments(style.name).segments];
+      const path = segments.join(".");
+      const other = seen.get(path);
+      if (other !== void 0) {
+        reportOnce(p, {
+          code: "path_collision",
+          severity: "error",
+          path,
+          message: "Two styles share this DTCG path after escaping; the later one was omitted.",
+          details: { id: style.id, ids: [other, style.id] }
+        });
+        continue;
+      }
+      seen.set(path, style.id);
+      setLeaf(tree, segments, leafOf(style, path));
+    }
+    files[file] = sortTree(tree);
+  };
+  build(
+    p.artifact.styles.typography,
+    "Typography styles",
+    "styles.typography.json",
+    (s, path) => typographyLeaf(p, s, path)
+  );
+  build(
+    p.artifact.styles.effects,
+    "Effect styles",
+    "styles.effects.json",
+    (s, path) => effectLeaf(p, s, path)
+  );
+  return files;
+}
+var pointer = (s) => s.replace(/~/g, "~0").replace(/\//g, "~1");
+var STYLE_ROOTS = {
+  "styles.typography.json": "Typography styles",
+  "styles.effects.json": "Effect styles"
+};
+function buildResolver(p, plans, styleFileNames) {
+  const sets = {};
+  const modifiers = {};
+  const order = [];
+  for (const collection of p.artifact.collections) {
+    const own = plans.filter((f) => f.collection.id === collection.id);
+    if (own.length === 0) continue;
+    const labels = p.modeLabelsById.get(collection.id) ?? modeLabels(collection);
+    const label = collectionLabelOf(p, collection);
+    if (own.length === 1) {
+      sets[label] = { sources: [{ $ref: own[0].file }] };
+      order.push({ $ref: `#/sets/${pointer(label)}` });
+      continue;
+    }
+    const contexts = {};
+    for (const plan of own) contexts[labels.get(plan.modeId) ?? plan.modeId] = [{ $ref: plan.file }];
+    const def = labels.get(collection.default_mode_id);
+    modifiers[label] = { contexts, ...def !== void 0 ? { default: def } : {} };
+    order.push({ $ref: `#/modifiers/${pointer(label)}` });
+  }
+  for (const file of styleFileNames) {
+    const root = STYLE_ROOTS[file];
+    sets[root] = { sources: [{ $ref: file }] };
+    order.push({ $ref: `#/sets/${pointer(root)}` });
+  }
+  const fileName = p.artifact.spec_layer.source.file_name;
+  return {
+    version: "2025.10",
+    ...typeof fileName === "string" && fileName.length > 0 ? { name: fileName } : {},
+    sets,
+    modifiers,
+    resolutionOrder: order
+  };
+}
+function annotateGroups(p, tree, collection) {
+  const groups = p.artifact.guidelines?.group_descriptions[collection.name];
+  if (!groups) return;
+  const head = dtcgSegments(collection.name).segments;
+  folders: for (const [folder, text] of Object.entries(groups)) {
+    if (text.length === 0) continue;
+    let node = tree;
+    for (const seg of [...head, ...dtcgSegments(folder).segments]) {
+      if (typeof node !== "object" || node === null || Array.isArray(node)) continue folders;
+      node = node[seg];
+    }
+    if (typeof node === "object" && node !== null && !Array.isArray(node) && !("$value" in node)) {
+      node.$description = text;
+    }
+  }
+}
+function foundationDtcg(artifact, options = {}) {
+  const p = {
+    artifact,
+    options: { values: options.values ?? "standard", ...options.units ? { units: options.units } : {} },
+    tokenById: new Map(artifact.tokens.map((t) => [t.id, t])),
+    tokenIds: new Set(artifact.tokens.map((t) => t.id)),
+    collectionById: new Map(artifact.collections.map((c) => [c.id, c])),
+    collectionLabelById: collectionLabels(artifact.collections),
+    modeLabelsById: new Map(artifact.collections.map((c) => [c.id, modeLabels(c)])),
+    pathById: /* @__PURE__ */ new Map(),
+    segmentsById: /* @__PURE__ */ new Map(),
+    omittedIds: /* @__PURE__ */ new Set(),
+    collidedIds: /* @__PURE__ */ new Set(),
+    report: [],
+    reportKeys: /* @__PURE__ */ new Set()
+  };
+  indexPaths(p);
+  omitInexpressibleTypes(p);
+  reportDuplicateCodeSyntax(p);
+  reportCollectionNameCollisions(p);
+  const files = {};
+  const plans = [];
+  const taken = new Set(RESERVED_FILE_NAMES);
+  for (const collection of artifact.collections) {
+    for (const mode of collection.modes) {
+      const tree = {};
+      for (const token of artifact.tokens) {
+        if (token.collection_id !== collection.id || p.omittedIds.has(token.id)) continue;
+        const leaf = tokenLeaf(p, token, collection, mode.id);
+        if (leaf) setLeaf(tree, p.segmentsById.get(token.id) ?? [], leaf);
+      }
+      annotateGroups(p, tree, collection);
+      const file = fileNameFor(collection, mode, taken);
+      plans.push({ collection, modeId: mode.id, file });
+      files[file] = sortTree(tree);
+    }
+  }
+  const styles = styleFiles(p);
+  Object.assign(files, styles);
+  const resolver = buildResolver(p, plans, Object.keys(styles).sort(compareCodeUnits));
+  p.report.sort((a, b) => compareCodeUnits(a.path, b.path) || compareCodeUnits(a.code, b.code) || compareCodeUnits(a.mode ?? "", b.mode ?? ""));
+  const meta = {};
+  for (const token of artifact.tokens) {
+    const collection = p.collectionById.get(token.collection_id);
+    if (!collection) continue;
+    const path = p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name;
+    meta[p.collidedIds.has(token.id) ? `${path} [${token.id}]` : path] = metaEntry(p, token, collection);
+  }
+  const sortedMeta = Object.fromEntries(Object.entries(meta).sort(([a], [b]) => compareCodeUnits(a, b)));
+  return { files, resolver, meta: sortedMeta, report: p.report };
+}
+function omitInexpressibleTypes(p) {
+  for (const token of p.artifact.tokens) {
+    if (token.type !== "string" && token.type !== "boolean") continue;
+    p.omittedIds.add(token.id);
+    reportOnce(p, {
+      code: "type_not_expressible",
+      severity: "warning",
+      path: p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name,
+      message: `DTCG has no ${token.type} type; the token was omitted.`,
+      details: { id: token.id, type: token.type }
+    });
+  }
+}
+function tokenLeaf(p, token, collection, modeId) {
+  const value = token.values[modeId];
+  const path = p.pathById.get(token.id) ?? "";
+  const mode = modeLabelOf(p, collection, modeId);
+  const description = token.description.length > 0 ? { $description: token.description } : {};
+  if (value === void 0 || value.kind === "missing") {
+    reportOnce(p, {
+      code: "value_omitted",
+      severity: "warning",
+      path,
+      mode,
+      message: "The token has no value for this mode.",
+      details: { id: token.id, reason: value?.reason ?? "no_value_for_mode" }
+    });
+    return null;
+  }
+  if (value.kind === "alias") {
+    if (value.resolved.status === "unresolved") {
+      reportOnce(p, {
+        code: "value_omitted",
+        severity: "warning",
+        path,
+        mode,
+        message: `The alias could not be resolved (${value.resolved.reason}); no value was written.`,
+        details: {
+          id: token.id,
+          reason: value.resolved.reason,
+          target_path: value.reference.target_path.join("/"),
+          ...value.reference.target_id !== null ? { target_id: value.reference.target_id } : {},
+          ...value.reference.source_library_name ? { source_library_name: value.reference.source_library_name } : {}
+        }
+      });
+      return null;
+    }
+    const targetId = value.reference.target_id;
+    const targetPath = targetId !== null && !p.omittedIds.has(targetId) ? p.pathById.get(targetId) : void 0;
+    if (targetPath === void 0) {
+      reportOnce(p, {
+        code: "value_omitted",
+        severity: "warning",
+        path,
+        mode,
+        message: "The alias target was itself omitted from the DTCG output.",
+        details: {
+          id: token.id,
+          reason: "target_omitted",
+          target_path: value.reference.target_path.join("/"),
+          ...targetId !== null ? { target_id: targetId } : {},
+          ...value.reference.source_library_name ? { source_library_name: value.reference.source_library_name } : {}
+        }
+      });
+      return null;
+    }
+    const target = targetId !== null ? p.tokenById.get(targetId) : void 0;
+    const hop = value.resolved.chain[0];
+    if (target && hop && target.collection_id !== token.collection_id) {
+      const targetCollection = p.collectionById.get(target.collection_id);
+      if (targetCollection !== void 0 && targetCollection.modes.length > 1 && modeName(targetCollection, hop.mode_id) !== modeName(collection, modeId)) {
+        const hopMode = modeLabelOf(p, targetCollection, hop.mode_id);
+        reportOnce(p, {
+          code: "mode_selection_not_expressible",
+          severity: "info",
+          path,
+          mode,
+          message: `Figma resolved this alias through the target's "${hopMode}" mode; DTCG resolves it by the consumer's context.`,
+          details: {
+            id: token.id,
+            target_id: targetId ?? "",
+            target_mode: hopMode,
+            resolved: asJson(value.resolved.value)
+          }
+        });
+      }
+    }
+    const typed = aliasLeafType(p, token, value.resolved.chain, value.resolved.value);
+    if ("omit" in typed) {
+      reportOnce(p, {
+        code: typed.omit,
+        severity: "warning",
+        path,
+        mode,
+        message: "The alias resolves to a value DTCG cannot state; the value was omitted.",
+        details: { id: token.id, ...typed.details }
+      });
+      return null;
+    }
+    return { $type: typed.$type, $value: `{${targetPath}}`, ...description };
+  }
+  const converted = projectedLiteral(p, token, value.value, (override) => {
+    reportOnce(p, {
+      code: "unit_override_conflicts_with_scope",
+      severity: "warning",
+      path,
+      message: "A unit override names this token but its scopes state a unitless number; the override was ignored.",
+      details: { id: token.id, override, scopes: [...token.scopes] }
+    });
+  });
+  if ("omit" in converted) {
+    reportOnce(p, {
+      code: converted.omit,
+      severity: "warning",
+      path,
+      mode,
+      message: converted.omit === "type_not_expressible" ? `DTCG has no ${String(converted.details.type)} type; the value was omitted.` : `DTCG dimensions take px or rem; a ${String(converted.details.unit)} value was omitted.`,
+      details: { id: token.id, ...converted.details }
+    });
+    return null;
+  }
+  return { $type: converted.$type, $value: converted.$value, ...description };
+}
+function dtcgExportFiles(out) {
+  const text = (v) => `${JSON.stringify(v, null, 2)}
+`;
+  const files = {};
+  for (const name of Object.keys(out.files).sort(compareCodeUnits)) files[name] = text(out.files[name]);
+  files["resolver.json"] = text(out.resolver);
+  files["spec-layer.meta.json"] = text(out.meta);
+  files["report.json"] = text(out.report);
+  return files;
+}
+
 // ../extractor/src/v5/componentContext.ts
 var import_js_sha2563 = __toESM(require_sha256(), 1);
 
@@ -748,14 +2045,14 @@ var LibraryBundleError = class extends Error {
     this.code = code;
   }
 };
-var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function hasContentHash(artifact) {
-  if (!isRecord(artifact) || !isRecord(artifact.spec_layer)) return false;
+  if (!isRecord2(artifact) || !isRecord2(artifact.spec_layer)) return false;
   const exp = artifact.spec_layer.export;
-  return isRecord(exp) && typeof exp.content_hash === "string";
+  return isRecord2(exp) && typeof exp.content_hash === "string";
 }
 function entry(v, where) {
-  if (!isRecord(v) || typeof v.name !== "string" || typeof v.ai !== "string" || !hasContentHash(v.artifact)) {
+  if (!isRecord2(v) || typeof v.name !== "string" || typeof v.ai !== "string" || !hasContentHash(v.artifact)) {
     throw new LibraryBundleError("malformed", `The ${where} entry in this bundle is malformed.`);
   }
   return { name: v.name, ai: v.ai, artifact: v.artifact };
@@ -772,7 +2069,7 @@ function parseLibraryBundle(input) {
       throw new LibraryBundleError("not_json", "This is not valid JSON.");
     }
   }
-  if (!isRecord(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
+  if (!isRecord2(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
     throw new LibraryBundleError("not_bundle", "This is not a Spec Layer library bundle.");
   }
   if (!supportedVersion(parsed.version)) {
@@ -788,7 +2085,7 @@ function parseLibraryBundle(input) {
   const foundationRaw = parsed.foundation ?? null;
   let foundation = null;
   if (foundationRaw !== null) {
-    if (!isRecord(foundationRaw) || typeof foundationRaw.ai !== "string" || !hasContentHash(foundationRaw.artifact)) {
+    if (!isRecord2(foundationRaw) || typeof foundationRaw.ai !== "string" || !hasContentHash(foundationRaw.artifact)) {
       throw new LibraryBundleError("malformed", "The foundation entry in this bundle is malformed.");
     }
     foundation = { ai: foundationRaw.ai, artifact: foundationRaw.artifact };
@@ -875,6 +2172,23 @@ function parseInclude(value) {
     components: record.components === void 0 ? null : record.components
   };
 }
+function parseDtcg(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalidConfig();
+  const record = value;
+  const out = {};
+  if (record.values !== void 0) {
+    if (record.values !== "standard" && record.values !== "legacy") throw invalidConfig();
+    out.values = record.values;
+  }
+  if (record.units !== void 0) {
+    if (typeof record.units !== "object" || record.units === null || Array.isArray(record.units)) throw invalidConfig();
+    for (const unit of Object.values(record.units)) {
+      if (unit !== "px" && unit !== "rem") throw invalidConfig();
+    }
+    out.units = record.units;
+  }
+  return out;
+}
 function readConfig(cwd) {
   const path = join2(cwd, CONFIG_NAME);
   if (!existsSync2(path)) return null;
@@ -889,14 +2203,16 @@ function readConfig(cwd) {
   return {
     ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
     ...typeof record.outDir === "string" ? { outDir: record.outDir } : {},
-    ...record.include !== void 0 ? { include: parseInclude(record.include) } : {}
+    ...record.include !== void 0 ? { include: parseInclude(record.include) } : {},
+    ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {}
   };
 }
 function writeConfig(cwd, config) {
   const body = {
     libraryId: config.libraryId,
     outDir: config.outDir,
-    ...config.include ? { include: config.include } : {}
+    ...config.include ? { include: config.include } : {},
+    ...config.dtcg ? { dtcg: config.dtcg } : {}
   };
   writeFileSync2(join2(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
 `);
@@ -922,6 +2238,7 @@ function resolveOptions(cwd, flags, env, manifestLibraryId) {
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
     key: supplied ?? storedKey,
     ...config?.include ? { include: config.include } : {},
+    ...config?.dtcg ? { dtcg: config.dtcg } : {},
     ...storedKeyFor ? { storedKeyFor } : {}
   };
 }
@@ -996,8 +2313,8 @@ Available: ${available || "none"}.`
 
 // src/files.ts
 function slugify(name) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug || "component";
+  const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug2 || "component";
 }
 function readManifest(outDir) {
   const path = join3(outDir, "manifest.json");
@@ -1022,20 +2339,20 @@ function componentSlugs(bundle) {
   const nextSuffix = /* @__PURE__ */ new Map();
   return bundle.components.map((component) => {
     const base = slugify(component.name);
-    let slug = base;
-    if (usedSlugs.has(slug)) {
+    let slug2 = base;
+    if (usedSlugs.has(slug2)) {
       let n = (nextSuffix.get(base) ?? 1) + 1;
-      slug = `${base}-${n}`;
-      while (usedSlugs.has(slug)) {
+      slug2 = `${base}-${n}`;
+      while (usedSlugs.has(slug2)) {
         n += 1;
-        slug = `${base}-${n}`;
+        slug2 = `${base}-${n}`;
       }
       nextSuffix.set(base, n);
     } else {
       nextSuffix.set(base, 1);
     }
-    usedSlugs.add(slug);
-    return slug;
+    usedSlugs.add(slug2);
+    return slug2;
   });
 }
 function assertReplaceable(outDir, cwd) {
@@ -1065,8 +2382,16 @@ function writeBundleFiles(opts) {
     put("bundle.json", opts.raw);
     const artifacts = [];
     if (opts.bundle.foundation) {
-      const aiPath = selection.foundation ? "ai/foundation.yaml" : null;
-      if (aiPath) put(aiPath, opts.bundle.foundation.ai);
+      let aiPath = null;
+      if (selection.foundation) {
+        const artifact = opts.bundle.foundation.artifact;
+        if (validateLevel1(artifact).some((d) => d.severity === "error")) {
+          throw new Error("The published Foundation context did not pass schema validation. Republish from the plugin, then pull again.");
+        }
+        const files = dtcgExportFiles(foundationDtcg(artifact, opts.dtcg ?? {}));
+        for (const [name, text] of Object.entries(files)) put(`tokens/${name}`, text);
+        aiPath = "tokens/resolver.json";
+      }
       artifacts.push({
         kind: "foundation",
         name: "foundation",
@@ -1091,7 +2416,8 @@ function writeBundleFiles(opts) {
       pluginVersion: opts.bundle.pluginVersion,
       extractorVersion: opts.bundle.extractorVersion,
       selection,
-      artifacts
+      artifacts,
+      ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {}
     };
     put("manifest.json", `${JSON.stringify(manifest, null, 2)}
 `);
@@ -1167,9 +2493,17 @@ function manifestReader() {
     return cache.get(outDir) ?? null;
   };
 }
-function sameSelection(a, b) {
-  const key = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
-  return key(a) === key(b);
+function sameOutput(a, b) {
+  const selectionKey = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
+  const dtcgKey = (d) => JSON.stringify(sortKeys(d ?? {}));
+  return selectionKey(a.selection) === selectionKey(b.selection) && dtcgKey(a.dtcg) === dtcgKey(b.dtcg);
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
+  }
+  return value;
 }
 var errorText = (err) => err instanceof Error ? err.message : String(err);
 function runInit(cwd, flags, io2) {
@@ -1248,7 +2582,13 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   }
   const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
   const keptInclude = include ?? existing?.include ?? null;
-  writeConfig(cwd, { libraryId: flags.id, outDir, ...keptInclude ? { include: keptInclude } : {} });
+  const keptDtcg = existing?.dtcg ?? null;
+  writeConfig(cwd, {
+    libraryId: flags.id,
+    outDir,
+    ...keptInclude ? { include: keptInclude } : {},
+    ...keptDtcg ? { dtcg: keptDtcg } : {}
+  });
   io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
   const ignored = ensureIgnored(cwd, CREDENTIALS_NAME);
   switch (ignored.kind) {
@@ -1301,7 +2641,10 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     return 1;
   }
   const manifest = manifestAt(join5(cwd, opts.outDir));
-  const etag = manifest && sameSelection(manifest.selection ?? DEFAULT_SELECTION, selection) ? manifest.bundleHash : void 0;
+  const etag = manifest && sameOutput(
+    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg },
+    { selection, dtcg: opts.dtcg }
+  ) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
     libraryId: opts.libraryId,
@@ -1329,7 +2672,8 @@ async function runPull(cwd, flags, env, io2, fetcher) {
       selection,
       libraryId: opts.libraryId,
       publishedAt: result.publishedAt,
-      bundleHash: result.bundleHash
+      bundleHash: result.bundleHash,
+      dtcg: opts.dtcg
     });
     io2.out(
       `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} (published ${result.publishedAt}).`
@@ -1440,11 +2784,11 @@ Commands:
                                                  store the key, then pull
   init    --id lib_... [--out DIR] [selection]   write speclayer.json
   pull    [--id lib_...] [--key sl_...] [selection]
-                                                 fetch the library into DIR (default .speclayer)
+                                                 fetch the library into DIR (default .speclayer); the foundation lands as DTCG under DIR/tokens/
   status  [--id lib_...] [--key sl_...]          check freshness; exits 2 when behind
   list                                           list every artifact in the last pull
   show    foundation | component NAME [--canonical]
-                                                 print one artifact's AI YAML (or canonical JSON)
+                                                 print one artifact (foundation: the DTCG document; component: its AI YAML; --canonical for JSON)
 
 Selection (setup, pull and init; flags replace the include block in speclayer.json):
   --only foundation | components   write just the foundation, or just components
@@ -1496,6 +2840,10 @@ async function main() {
     return 1;
   }
 }
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") process.exit(process.exitCode ?? 0);
+  throw err;
+});
 process.exitCode = await main();
 /*! Bundled license information: