Source format reference

Studio source is the structured state behind the active artifact. It is available to people through Code and to agents through window.glyphfield.studio.readSource() and applySource().

Rules shared by every tool

• Source must parse as a JSON object. Arrays and primitive top-level values are rejected.
• Each tool validates its own enums, ranges, references, and required collections before changing visible state.
• Failed application leaves the current artifact unchanged and reports the error.
• A successful application updates the same state used by the inspector, preview, persistence, and export.
• Browser source is not automatically a POST /api/generate request. Only a design-sequence response explicitly contains an apply-ready document; that compact version-3 compatibility source is normalized to the current CanvasDocument when applied.
• Preserve unknown fields. Forward compatibility depends on editing the current document rather than reconstructing an older example.

Portable CanvasDocument

Design Lab is backed by the shared CanvasDocument scene graph. The current canvas schema is schemaVersion: 2; Design Lab-specific metadata records sourceVersion: 4.

{
  "schemaVersion": 2,
  "id": "design-lab:gt:wide",
  "brandId": "gt",
  "capabilities": ["animation", "assets", "constraints", "guides", "history", "layers", "pages", "text"],
  "pageIds": ["page-1"],
  "pages": {
    "page-1": {
      "width": 1920,
      "height": 1080,
      "background": "#111216",
      "elementIds": ["shader-1", "text-1", "brand-mark"]
    }
  },
  "elements": {},
  "assets": {},
  "metadata": {
    "tool": "design-lab",
    "designLab": {
      "sourceVersion": 4,
      "ratio": "wide",
      "exportSettings": {},
      "shaderSequence": {},
      "timeline": {},
      "layerShaders": {},
      "groups": [],
      "workspace": {}
    }
  }
}

The complete document also carries timestamps, revision, fonts, resources, saved versions, and element records. Each element owns bounds, constraints, visibility, style, opacity, blend mode, and tool-specific data. Image and logo elements reference asset records rather than browser-only paths.

Generated compatibility source

POST /api/generate with kind: "design-sequence" returns an HTTP envelope with schemaVersion: 1 and a compact document whose version is 3. That document uses composition, ratio, timeline, shaderSequence, and exportSettings fields. It is an input contract, not the current CanvasDocument envelope. Apply it, then call readSource() to receive the normalized CanvasDocument shown above.

Design Lab layer data

Design Lab supports these element/layer families:

page.elementIds is the authoritative back-to-front layer order. Groups are stored in Design Lab metadata and must reference valid element IDs. Shader layers remain below content during reconciliation.

Tool document map

Safe agent mutation

const studio = window.glyphfield.studio;
const before = JSON.parse(studio.readSource());

// Preserve the envelope and change only the intended element.
const text = Object.values(before.elements)
  .find((element) => element.kind === 'text');
if (!text) throw new Error('No text element exists.');

text.content = 'Every language. One source.';
text.style.opacity = 0.92;

await studio.applySource(before);

const after = JSON.parse(studio.readSource());
if (after.elements[text.id].content !== text.content) {
  throw new Error('The change did not round-trip.');
}

Use describe().source before reading or applying. Do not write directly to localStorage, IndexedDB, component state, or internal React properties.

Lottie validation

{
  "v": "5.12.2",
  "fr": 30,
  "ip": 0,
  "op": 90,
  "w": 1200,
  "h": 750,
  "layers": []
}

The browser player decides support for individual Lottie features. Recoloring, trim, and frame selection are Studio state; downloading edited JSON emits the updated vector document. An imported .lottie bundle can be replayed and downloaded but is not presented as editable raw JSON unless a JSON source exists.

Portability checklist

1. Read and retain the current schema/source versions.
2. Preserve asset records, page ordering, unknown metadata, and stable element IDs.
3. Apply through the tool validator and re-read.
4. Save the source or named design when later regeneration matters.
5. Export the requested rendered format separately.
6. Carry authorized fonts/assets with the document when they are not embedded.

See Source code editing, Studio Browser API, and Formats and portability.

For migration behavior and the relationship between these independent version numbers, see Version compatibility.