Source format reference

Studio source is the structured JSON state behind the active artifact. People edit it in the source drawer, which the Code button opens. Scripts and agents read and apply it through the Browser API with window.glyphfield.studio.readSource() and applySource().

The source stays available while its Studio tool is active, whether or not the source drawer is open. Brand book source holds only presentation edits (order, visibility, layout, surface, image and copy). Its content still comes from the Brand identity tool.

Rules for 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 it changes visible state.
• When application fails, the current artifact stays unchanged and the error is reported.
• A successful application updates the same state that the inspector, preview, persistence and export use.
• Browser source is not a POST /api/generate request. Only a design-sequence response contains an apply-ready document, and that compact version-3 compatibility source is normalized to the current CanvasDocument when it is applied.
• Keep unknown fields. Edit the current document instead of rebuilding an older example, so fields added by newer versions survive.

Portable CanvasDocument

Design Lab, the layered composition tool, stores its work in the shared CanvasDocument scene graph. The current canvas schema is schemaVersion: 2, and the Design Lab metadata records sourceVersion: 4.

{
  "schemaVersion": 2,
  "brandId": "gt",
  "capabilities": ["animation", "assets", "constraints", "guides", "history", "layers", "pages", "text"],
  "pageIds": ["<page id>"],
  "pages": {
    "<page id>": {
      "width": 1600,
      "height": 900,
      "background": "#070707",
      "elementIds": ["shader-canvas-1", "text-1", "logo-brand"]
    }
  },
  "elements": {},
  "assets": {},
  "metadata": {
    "tool": "design-lab",
    "designLab": {
      "sourceVersion": 4,
      "ratio": "wide",
      "exportSettings": {},
      "shaderSequence": {},
      "timeline": {},
      "layerShaders": {},
      "groups": [],
      "workspace": { "activeArtboardId": "artboard-main", "activeSurfaceId": "artboard-main", "artboards": [], "canvas": {} }
    }
  }
}

The complete document also carries id, title, timestamps, revision, guides and the element records. Keep them exactly as readSource() returns them.

Each element has bounds, constraints, hidden, locked, a style with opacity and blend mode, and tool-specific data that holds the full layer settings and the layerType. A text element keeps its text in content. Bounds x and y are positions. Bounds width and height are scale factors of the layer's default box. They are not pixel values. Bounds rotation is the layer's angle in degrees, clockwise about its center, from −180 to 180. The layer data mirrors a nonzero angle as transform.rotation, and bounds.rotation wins when the two differ. Documents saved before layers could rotate have no transform.rotation and load at 0. Effect elements always have rotation 0.

Image and logo elements reference asset records instead of browser-only paths. Identity assets use brand-asset:<library id>, and embedded files use resource:<layer id>. Layer IDs start with shader-, effect-, text-, logo- or asset-. Group IDs start with group-, and artboard IDs start with artboard-. metadata.designLab.identity holds the typography snapshot of an imported project.

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 the fields composition, ratio, timeline, shaderSequence and exportSettings. It is an input format and is not the current CanvasDocument. Apply it, then call readSource() to receive the normalized CanvasDocument shown above.

Design Lab layer data

page.elementIds is the authoritative layer order from back to front. Groups are stored in the Design Lab metadata and must reference valid element IDs. When a shader layer is missing from the stored order, it is inserted behind the content. An authored order is kept.

Captured shader appearance

A shader application can carry frameState and frameSnapshot, which have different jobs:

• frameState is the editable anchor of the native recipe: provider, floating-point engine time or frame, timeline time, material ID and any captured input that a provider needs. Current records are version 2, and older Paper version-1 anchors still load.
• frameSnapshot is { version: 1, assetId, width, height } and references a lossless PNG in CanvasDocument.assets. Its ID has the form shader-frame:<sha256>, so repeated uses share the same bytes. Keep unknown snapshot fields when editing.

Shader layers keep these records in element data. Shader fills on content layers keep them in metadata.designLab.layerShaders. Workspace artboards keep their own snapshots. timeline.timeMs stores time separately from the older timeline.frame export frame index.

An ordinary pause can update frameState and the timeline without creating a PNG frameSnapshot. Playback, extending the time range, and PNG, JPG, GIF and MP4 export do not add captured-frame assets. Capturing an appearance is a separate, explicit operation.

Captured frames use durable local asset references instead of temporary blob: URLs. Portable JSON embeds the PNG bytes, and source application validates and imports them before it changes the composition. A missing frame produces an error that says what is missing, and the layer does not fall back to the default shader. A PNG keeps the captured appearance at its recorded resolution. It does not store an editable Fluid Energy simulation state, and the same procedural settings can render slightly differently on another GPU.

Tool document map

Safe agent edits

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

// Keep 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.');
}

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

Lottie validation

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

The browser player decides which Lottie features render. Recoloring, trimming and frame selection are Studio state. lottie.export.source and Export JSON write the updated vector document. An imported .lottie archive can be replayed and downloaded, but its layers, text and colors cannot be edited.

Portability checklist

1. Read and keep the current schema and source versions.
2. Keep asset records, page order, unknown metadata and stable element IDs.
3. Apply through the tool validator and read the source again.
4. Save the source or a named design when the work may need to be regenerated.
5. Export the requested rendered format separately.
6. Keep authorized font and asset files with the document when they are not embedded.

Source code editing, Studio Browser API and Formats and portability cover related tasks. Version compatibility explains how these independent version numbers relate and how migration works.