Skip to content

The VS Code of video editing, built for agents.

TypeScript
5.8 KB
Raw Blame
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * How the compile step, the host and the editor agree to name the elements of
 * a project's source. Everything here is data all three sides read; none of
 * them import each other, and nothing here touches a file or a host.
 *
 * It exists so that a change made on the canvas can be written back to the JSX
 * that produced it: the compile step stamps every composition element with
 * where it came from, the host keeps that stamp on the entity it builds, and
 * the editor hands it back when it wants the source changed.
 */

/**
 * Attribute an element may carry to name itself. An id outlives edits that
 * renumber the file, so it — not the element's position — is what an entity
 * holds once its element has one. It is also how elements point at each other
 * within a render: `syncTo` names the id of the clip it aligns against.
 *
 * Yours to write: an id is any string, and `id="hero"` is worth more to read
 * than anything generated. The editor only stamps elements that have none, and
 * renaming one by hand is safe. Stripped at compile time, so it never reaches
 * a host as a prop; what survives is `SOURCE_ATTR`, which carries it.
 */
export const ID_ATTR = "id";

/**
 * Attribute the compile step stamps onto every composition element, carrying
 * `<file relative to the project>:<id, or position in document order>`.
 * It is what lets an entity be traced back to the JSX that produced it.
 */
export const SOURCE_ATTR = "__source";

/**
 * Attribute the compile step stamps onto every composition element that sits
 * in the body of a `<For>` or `<Index>`, carrying the source of that loop
 * (`<file>:<position of the loop element>`). Every iteration renders the same
 * element, so its entities share one `SOURCE_ATTR` and cannot be written to
 * one at a time; the loop stamp is what lets the editor tell that, gather the
 * loop's entities, and have the source unrolled into one element per
 * iteration before it writes. Only the nearest loop is named: an element in a
 * loop within a loop is that inner loop's business.
 */
export const LOOP_ATTR = "__loop";

/** The Solid control-flow components whose children render once per item. */
export const LOOP_TAGS: readonly string[] = ["For", "Index"];

export const isLoopTag = (tag: string): boolean => LOOP_TAGS.includes(tag);

/**
 * What a prop can be worth in a source file: JSON, essentially. It is the
 * vocabulary an edit is expressed in — the value as a project would have
 * written it, not as a host happens to store it, so a color travels as
 * "#161616" rather than as the number the runtime packs it into.
 */
export type PropValue = number | string | boolean | null | PropValue[] | { [key: string]: PropValue };

/**
 * Whether a value is one a source file could spell — a `PropValue`. An
 * instance of a class (a `Date`, say) is not, however plain its fields:
 * spelled as an object literal it would read back as something else.
 */
export function isPropValue(value: unknown): value is PropValue {
  if (value === null) return true;
  switch (typeof value) {
    case "string":
    case "number":
    case "boolean":
      return true;
    case "object": {
      if (Array.isArray(value)) return value.every(isPropValue);
      const prototype = Object.getPrototypeOf(value);
      return (prototype === Object.prototype || prototype === null) && Object.values(value as object).every(isPropValue);
    }
    default:
      return false;
  }
}

/**
 * The composition elements — the tags that become entities. Everything else a
 * project renders is either a user component or DOM content under
 * `<htmlPaint>`, neither of which a stamp would mean anything for.
 *
 * Kept in step with the `IntrinsicElements` of "./jsx-runtime" by hand: that
 * one declares types for a compiler, this one is read at runtime.
 */
export const COMPOSITION_TAGS = [
  "stage",
  "scene",
  "group",
  "rect",
  "ellipse",
  "polygon",
  "path",
  "video",
  "image",
  "audio",
  "text",
  "textRange",
  "sequence",
  "captions",
  "adjustmentLayer",
  "solidPaint",
  "linearGradientPaint",
  "radialGradientPaint",
  "angularGradientPaint",
  "imagePaint",
  "videoPaint",
  "colorStop",
  "stroke",
  "shadow",
  "effect",
  "clipPath",
  "mask",
  "animation",
  "keyframeTrack",
  "keyframe",
  "htmlPaint",
  "html",
  "shaderPaint",
  "surfacePaint",
  "surface",
] as const;

export type CompositionTag = (typeof COMPOSITION_TAGS)[number];

const TAGS: ReadonlySet<string> = new Set(COMPOSITION_TAGS);

/**
 * Whether a tag names a composition element, in either spelling: the camelCase
 * intrinsics a project is authored in, and the PascalCase components the
 * compile step canonicalizes them into (see @diffusionstudio/reconciler's
 * "elements"). Both are the same element, so both are stamped.
 */
export function isCompositionTag(tag: string): boolean {
  return TAGS.has(tag) || TAGS.has(tag.charAt(0).toLowerCase() + tag.slice(1));
}

/**
 * A source id is `file:locator`, where a numeric locator is the element's
 * position in document order and anything else is its id. The file is where the
 * element was last seen: an id that moved to another file reads as gone rather
 * than as some other element, which is the safe way to be wrong.
 */
export function parseSource(id: string): { file: string; locator: number | string } | undefined {
  const at = id.lastIndexOf(":");
  if (at < 0) return undefined;

  const suffix = id.slice(at + 1);
  if (!suffix) return undefined;

  const index = Number(suffix);
  return { file: id.slice(0, at), locator: Number.isInteger(index) ? index : suffix };
}

/** The inverse of `parseSource`. */
export const formatSource = (file: string, locator: number | string): string => `${file}:${locator}`;