@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/synthesize-K62TIZWI.js

@@ -0,0 +1,182 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+var require = __hf_createRequire(import.meta.url);
+var __filename = __hf_fileURLToPath(import.meta.url);
+var __dirname = __hf_dirname(__filename);
+import {
+  DEFAULT_VOICE,
+  ensureModel,
+  ensureVoices,
+  inferLangFromVoiceId
+} from "./chunk-XZABUQTX.js";
+import {
+  findPython,
+  hasPythonPackage
+} from "./chunk-5ETJX6WM.js";
+import {
+  writeNewFileSync
+} from "./chunk-4YYJOFKS.js";
+import "./chunk-X5HWXQPU.js";
+import "./chunk-M2WBOQ2Q.js";
+
+// src/tts/synthesize.ts
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, readdirSync, unlinkSync } from "fs";
+import { join, dirname, basename } from "path";
+import { homedir } from "os";
+var SYNTH_SCRIPT = `
+import sys, json, inspect, re
+
+model_path = sys.argv[1]
+voices_path = sys.argv[2]
+text = sys.argv[3]
+voice = sys.argv[4]
+speed = float(sys.argv[5])
+output_path = sys.argv[6]
+lang = sys.argv[7] if len(sys.argv) > 7 else ""
+
+import kokoro_onnx
+import soundfile as sf
+
+model = kokoro_onnx.Kokoro(model_path, voices_path)
+
+kwargs = {"voice": voice, "speed": speed}
+supports_lang = "lang" in inspect.signature(model.create).parameters
+if lang and supports_lang:
+    kwargs["lang"] = lang
+
+def is_voice_token_overflow(error):
+    return bool(re.search(
+        r"index \\d+ is out of bounds for axis 0 with size 510",
+        str(error),
+        re.IGNORECASE,
+    ))
+
+def split_for_retry(value):
+    midpoint = len(value) // 2
+    boundaries = [
+        index + 1
+        for index, char in enumerate(value)
+        if (char in "\u3002\uFF01\uFF1F!?\\n" or char.isspace()) and 0 < index < len(value) - 1
+    ]
+    split_at = min(boundaries, key=lambda index: abs(index - midpoint)) if boundaries else midpoint
+    return value[:split_at], value[split_at:]
+
+def synthesize_text(value):
+    try:
+        return model.create(value, **kwargs)
+    except IndexError as error:
+        if not is_voice_token_overflow(error) or len(value) < 2:
+            raise
+        left, right = split_for_retry(value)
+        left_samples, left_rate = synthesize_text(left)
+        right_samples, right_rate = synthesize_text(right)
+        if left_rate != right_rate:
+            raise RuntimeError("Kokoro returned inconsistent sample rates across text chunks")
+        samples = list(left_samples)
+        samples.extend(right_samples)
+        return samples, left_rate
+
+samples, sample_rate = synthesize_text(text)
+sf.write(output_path, samples, sample_rate)
+
+duration = len(samples) / sample_rate
+print(json.dumps({
+    "outputPath": output_path,
+    "sampleRate": sample_rate,
+    "durationSeconds": round(duration, 3),
+    "langApplied": bool(lang and supports_lang),
+}))
+`;
+var ESPEAK_LANG_OVERRIDES = {
+  zh: "cmn"
+};
+var SCRIPT_DIR = join(homedir(), ".cache", "hyperframes", "tts");
+var SCRIPT_PATH = join(SCRIPT_DIR, "synth-v3.py");
+function ensureSynthScript() {
+  if (!existsSync(SCRIPT_PATH)) {
+    mkdirSync(SCRIPT_DIR, { recursive: true });
+    writeNewFileSync(SCRIPT_PATH, SYNTH_SCRIPT);
+    const currentName = basename(SCRIPT_PATH);
+    try {
+      for (const entry of readdirSync(SCRIPT_DIR)) {
+        if (entry !== currentName && /^synth(-v\d+)?\.py$/.test(entry)) {
+          try {
+            unlinkSync(join(SCRIPT_DIR, entry));
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return SCRIPT_PATH;
+}
+async function synthesize(text, outputPath, options) {
+  const voice = options?.voice ?? DEFAULT_VOICE;
+  const speed = options?.speed ?? 1;
+  const lang = options?.lang ?? inferLangFromVoiceId(voice);
+  options?.onProgress?.("Checking Python runtime...");
+  const python = findPython();
+  if (!python) {
+    throw new Error(
+      "Python 3 is required for text-to-speech. Install Python 3.10+ and run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)"
+    );
+  }
+  if (!hasPythonPackage(python, "kokoro_onnx")) {
+    throw new Error(
+      "The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)"
+    );
+  }
+  if (!hasPythonPackage(python, "soundfile")) {
+    throw new Error("The soundfile package is not installed. Run: pip install soundfile");
+  }
+  const [modelPath, voicesPath] = await Promise.all([
+    ensureModel(options?.model, { onProgress: options?.onProgress }),
+    ensureVoices({ onProgress: options?.onProgress })
+  ]);
+  const scriptPath = ensureSynthScript();
+  mkdirSync(dirname(outputPath), { recursive: true });
+  options?.onProgress?.(`Generating speech with voice ${voice} (${lang})...`);
+  try {
+    const espeakLang = ESPEAK_LANG_OVERRIDES[lang] ?? lang;
+    const stdout = execFileSync(
+      python,
+      [scriptPath, modelPath, voicesPath, text, voice, String(speed), outputPath, espeakLang],
+      {
+        encoding: "utf-8",
+        timeout: 3e5,
+        stdio: ["pipe", "pipe", "pipe"]
+      }
+    );
+    if (!existsSync(outputPath)) {
+      throw new Error("Synthesis completed but no output file was created");
+    }
+    const lines = stdout.trim().split("\n");
+    const jsonLine = lines[lines.length - 1] ?? "";
+    const result = JSON.parse(jsonLine);
+    return {
+      outputPath: result.outputPath,
+      sampleRate: result.sampleRate,
+      durationSeconds: result.durationSeconds,
+      langApplied: result.langApplied
+    };
+  } catch (err) {
+    if (err instanceof SyntaxError && existsSync(outputPath)) {
+      throw new Error(
+        "Speech was generated but metadata could not be read. Check the output file manually."
+      );
+    }
+    let detail = "";
+    if (err && typeof err === "object" && "stderr" in err) {
+      const stderr = String(err.stderr).trim();
+      if (stderr) detail = `
+${stderr.slice(-500)}`;
+    }
+    throw new Error(`Speech synthesis failed${detail}`);
+  }
+}
+export {
+  synthesize
+};

package/vendor/hyperframes/dist/system-EZYZNUFD.js

@@ -0,0 +1,44 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+var require = __hf_createRequire(import.meta.url);
+var __filename = __hf_fileURLToPath(import.meta.url);
+var __dirname = __hf_dirname(__filename);
+import {
+  bytesToMb,
+  getAvailableMemoryMb,
+  getFreeDiskMb,
+  getPowerState,
+  getShmSizeMb,
+  getSystemMeta,
+  parsePmsetPowerSource
+} from "./chunk-IUZFXWSV.js";
+import "./chunk-AMKC3AXA.js";
+import "./chunk-K2FTXJYH.js";
+import "./chunk-2YN64IN5.js";
+import "./chunk-AVUUN2XD.js";
+import "./chunk-DPVXBVLL.js";
+import "./chunk-Z6B37SNM.js";
+import "./chunk-HWKCIWQT.js";
+import "./chunk-VC76R6W2.js";
+import "./chunk-OFQWTKPW.js";
+import "./chunk-TWWSYAKJ.js";
+import "./chunk-ZJUKFZ2P.js";
+import "./chunk-HBBJFK6I.js";
+import "./chunk-PJ3HDUCY.js";
+import "./chunk-TQFG7HTI.js";
+import "./chunk-GK4AIFIH.js";
+import "./chunk-2PSPARWP.js";
+import "./chunk-3GXQPCJC.js";
+import "./chunk-RQVDTPGD.js";
+import "./chunk-PMRBLBUP.js";
+import "./chunk-M2WBOQ2Q.js";
+export {
+  bytesToMb,
+  getAvailableMemoryMb,
+  getFreeDiskMb,
+  getPowerState,
+  getShmSizeMb,
+  getSystemMeta,
+  parsePmsetPowerSource
+};

package/vendor/hyperframes/dist/telemetry-2YC4SGQU.js

@@ -0,0 +1,144 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+var require = __hf_createRequire(import.meta.url);
+var __filename = __hf_fileURLToPath(import.meta.url);
+var __dirname = __hf_dirname(__filename);
+import {
+  c
+} from "./chunk-ZTZA4UWZ.js";
+import {
+  defineCommand
+} from "./chunk-S3S4TGEH.js";
+import {
+  failCommand
+} from "./chunk-PBN6GBJE.js";
+import {
+  CONFIG_PATH,
+  STATE_PATH,
+  effectiveTelemetryStatus,
+  readConfigFresh,
+  writeConfigWithResult
+} from "./chunk-XUXGIA7H.js";
+import "./chunk-WERLJGIC.js";
+import "./chunk-ISN5GRYI.js";
+import "./chunk-KNU5COPB.js";
+import "./chunk-M2WBOQ2Q.js";
+
+// src/commands/telemetry.ts
+var examples = [
+  ["Check current telemetry status", "hyperframes telemetry status"],
+  ["Disable telemetry", "hyperframes telemetry disable"],
+  ["Enable telemetry", "hyperframes telemetry enable"]
+];
+function describeOverride(source) {
+  switch (source) {
+    case "HYPERFRAMES_NO_TELEMETRY":
+    case "DO_NOT_TRACK":
+      return `${source} is set`;
+    case "dev_mode":
+      return "this is a development build";
+    case "telemetry_disabled_build":
+      return "this build has no telemetry key";
+  }
+}
+function setTelemetryEnabled(enabled) {
+  const config = readConfigFresh();
+  config.telemetryEnabled = enabled;
+  const result = writeConfigWithResult(config);
+  if (!result.ok) {
+    console.error(
+      `
+  ${c.error("\u2717")}  Could not persist telemetry preference to ${c.accent(CONFIG_PATH)}
+  ${c.dim("Reason:")} ${result.error}
+`
+    );
+    failCommand();
+  }
+  const effective = effectiveTelemetryStatus(enabled);
+  const preference = enabled ? c.success("enabled") : c.bold("disabled");
+  const noun = enabled && !effective.enabled ? "Telemetry preference" : "Telemetry";
+  console.log(`
+  ${c.success("\u2713")}  ${noun} ${preference}`);
+  if (effective.source !== "config") {
+    console.log(
+      `  ${c.dim("Note:")} Telemetry remains disabled because ${describeOverride(effective.source)}.`
+    );
+  }
+  console.log();
+}
+function runStatus() {
+  const config = readConfigFresh();
+  const effective = effectiveTelemetryStatus(config.telemetryEnabled);
+  const status = effective.enabled ? c.success("enabled") : c.dim("disabled");
+  console.log();
+  console.log(`  ${c.dim("Status:")}     ${status}`);
+  console.log(`  ${c.dim("Source:")}     ${effective.source}`);
+  console.log(`  ${c.dim("Config:")}     ${c.accent(CONFIG_PATH)}`);
+  console.log(`  ${c.dim("State:")}      ${c.accent(STATE_PATH)}`);
+  console.log(`  ${c.dim("Tracked commands:")} ${c.bold(String(config.commandCount))}`);
+  console.log();
+  console.log(`  ${c.dim("Disable:")}    ${c.accent("hyperframes telemetry disable")}`);
+  console.log(
+    `  ${c.dim("Env var:")}    ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("or")} ${c.accent("DO_NOT_TRACK=1")}`
+  );
+  console.log();
+}
+var telemetry_default = defineCommand({
+  meta: { name: "telemetry", description: "Manage anonymous usage telemetry" },
+  args: {
+    subcommand: {
+      type: "positional",
+      description: "Subcommand: enable, disable, status",
+      required: false
+    }
+  },
+  async run({ args }) {
+    const subcommand = args.subcommand;
+    if (!subcommand || subcommand === "") {
+      console.log(`
+${c.bold("hyperframes telemetry")} ${c.dim("<subcommand>")}
+
+Manage anonymous usage data collection.
+
+${c.bold("SUBCOMMANDS:")}
+  ${c.accent("status")}    ${c.dim("Show current telemetry status")}
+  ${c.accent("enable")}    ${c.dim("Enable anonymous telemetry")}
+  ${c.accent("disable")}   ${c.dim("Disable anonymous telemetry")}
+
+${c.bold("WHAT WE COLLECT:")}
+  ${c.dim("\u2022")} Command names (init, render, preview, etc.)
+  ${c.dim("\u2022")} Render performance (duration, fps, quality)
+  ${c.dim("\u2022")} Template choices
+  ${c.dim("\u2022")} OS, architecture, Node.js version, CLI version
+
+${c.bold("WHAT WE DON'T COLLECT:")}
+  ${c.dim("\u2022")} File paths, project names, or video content
+  ${c.dim("\u2022")} IP addresses (discarded by our analytics provider)
+  ${c.dim("\u2022")} Any personally identifiable information
+
+${c.dim("You can also set")} ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("or")} ${c.accent("DO_NOT_TRACK=1")} ${c.dim("to disable.")}
+`);
+      return;
+    }
+    switch (subcommand) {
+      case "enable":
+        return setTelemetryEnabled(true);
+      case "disable":
+        return setTelemetryEnabled(false);
+      case "status":
+        return runStatus();
+      default:
+        console.error(
+          `${c.error("Unknown subcommand:")} ${subcommand}
+
+Run ${c.accent("hyperframes telemetry --help")} for usage.`
+        );
+        failCommand();
+    }
+  }
+});
+export {
+  telemetry_default as default,
+  examples
+};

package/vendor/hyperframes/dist/telemetry-QMYM4WME.js

@@ -0,0 +1,95 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+var require = __hf_createRequire(import.meta.url);
+var __filename = __hf_fileURLToPath(import.meta.url);
+var __dirname = __hf_dirname(__filename);
+import {
+  identifyUser,
+  trackAuthLoginCompleted,
+  trackAuthLoginFailed,
+  trackAuthLoginStarted,
+  trackBrowserInstall,
+  trackCliError,
+  trackCommand,
+  trackCommandResult,
+  trackFigmaImport,
+  trackInitTemplate,
+  trackRenderComplete,
+  trackRenderError
+} from "./chunk-JTHMTOMQ.js";
+import {
+  flush,
+  flushSync,
+  shouldTrack,
+  showTelemetryNotice,
+  trackEvent
+} from "./chunk-EISRN4E6.js";
+import "./chunk-VWG7OQKU.js";
+import "./chunk-ZTZA4UWZ.js";
+import {
+  bytesToMb,
+  getFreeDiskMb,
+  getShmSizeMb,
+  getSystemMeta
+} from "./chunk-IUZFXWSV.js";
+import "./chunk-AMKC3AXA.js";
+import "./chunk-54HJ63Q2.js";
+import "./chunk-PBN6GBJE.js";
+import "./chunk-K2FTXJYH.js";
+import "./chunk-2YN64IN5.js";
+import "./chunk-AVUUN2XD.js";
+import "./chunk-DPVXBVLL.js";
+import "./chunk-Z6B37SNM.js";
+import "./chunk-HWKCIWQT.js";
+import "./chunk-VC76R6W2.js";
+import "./chunk-OFQWTKPW.js";
+import "./chunk-TWWSYAKJ.js";
+import "./chunk-ZJUKFZ2P.js";
+import "./chunk-HBBJFK6I.js";
+import "./chunk-PJ3HDUCY.js";
+import "./chunk-TQFG7HTI.js";
+import "./chunk-GK4AIFIH.js";
+import "./chunk-2PSPARWP.js";
+import "./chunk-K4WIOZFP.js";
+import {
+  CONFIG_PATH,
+  incrementCommandCount,
+  readConfig,
+  writeConfig
+} from "./chunk-XUXGIA7H.js";
+import "./chunk-WERLJGIC.js";
+import "./chunk-ISN5GRYI.js";
+import "./chunk-FLWXXDNS.js";
+import "./chunk-KNU5COPB.js";
+import "./chunk-3GXQPCJC.js";
+import "./chunk-RQVDTPGD.js";
+import "./chunk-PMRBLBUP.js";
+import "./chunk-M2WBOQ2Q.js";
+export {
+  CONFIG_PATH,
+  bytesToMb,
+  flush,
+  flushSync,
+  getFreeDiskMb,
+  getShmSizeMb,
+  getSystemMeta,
+  identifyUser,
+  incrementCommandCount,
+  readConfig,
+  shouldTrack,
+  showTelemetryNotice,
+  trackAuthLoginCompleted,
+  trackAuthLoginFailed,
+  trackAuthLoginStarted,
+  trackBrowserInstall,
+  trackCliError,
+  trackCommand,
+  trackCommandResult,
+  trackEvent,
+  trackFigmaImport,
+  trackInitTemplate,
+  trackRenderComplete,
+  trackRenderError,
+  writeConfig
+};

package/vendor/hyperframes/dist/templates/_shared/AGENTS.md

@@ -0,0 +1,107 @@
+# HyperFrames Composition Project
+
+## Skills — USE THESE FIRST
+
+**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.
+
+**Doing anything with HyperFrames?** Start at `/hyperframes` — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), confirms your brief up front (the intent layer), and routes every "make me a…" request (a video, a deck, a composition port) to the right workflow. Read it first, especially when there's no project context to orient you. The workflows it routes to:
+
+- `/product-launch-video` — any **website** URL or brief / script → a product launch / SaaS / promo video, or a site tour / showcase featuring the site's own captured visuals.
+- `/faceless-explainer` — arbitrary text (topic / article / notes), **no URL, no website capture** → 60-90s faceless explainer.
+- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched.
+- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.)
+- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor).
+- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
+- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
+- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
+- `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length.
+
+**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above.
+
+The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-keyframes`, `/hyperframes-creative`, `/hyperframes-cli`, `/media-use`, `/hyperframes-audio`, `/hyperframes-registry`, `/figma`) and the full capability map live inside `/hyperframes` — it is the single source of truth for which skill handles which intent.
+
+**Changing how real footage or images look or reveal?** Load `/media-use` and read its `references/media-treatments.md` before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays.
+
+> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`.
+
+> **Using a HyperFrames plugin?** Load skills from that installed bundle and follow
+> its `hyperframes/references/plugin-installation.md` execution rules. Update via
+> the plugin manager, not the standalone commands below.
+>
+> **Standalone skill missing or stale?** Run `npx hyperframes skills update <name>` to install/refresh
+> the specific skill you need (the `/hyperframes` router does this automatically before
+> entering a workflow), or bare `npx hyperframes skills update` to refresh the core set plus
+> everything already installed — neither pulls the full set. Restart the agent session so
+> newly installed skills load.
+
+## Commands
+
+```bash
+npm run dev          # human-operated foreground preview (blocks until stopped)
+npx hyperframes preview --background  # agent-safe persistent Studio preview
+npx hyperframes preview --status      # verify the persistent preview is listening
+npx hyperframes preview --stop        # stop it when review is finished
+npm run check        # lint + runtime + layout + motion + contrast (one command)
+npm run render       # render to MP4
+npm run publish      # publish and get a shareable link
+npx hyperframes lint --verbose  # include info-level findings
+npx hyperframes lint --json     # machine-readable output for CI
+npx hyperframes docs <topic> # reference docs in terminal
+```
+
+> **Agents must use `npx hyperframes preview --background` for Studio handoff.** Do not rely
+> on a shell/tool `run_in_background` wrapper around `npm run dev`: that foreground process
+> remains owned by the invoking session and can disappear while the browser stays open,
+> leaving refreshes at `ERR_CONNECTION_TIMED_OUT`. Verify with `preview --status`, keep it
+> alive through review, and stop it explicitly with `preview --stop` afterward.
+
+> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: `npx hyperframes@latest upgrade --project . --check` (shows the delta), then `npx hyperframes@latest upgrade --project .` to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself.
+
+## Documentation
+
+**For quick reference**, use the local CLI docs command (no network required):
+
+```bash
+npx hyperframes docs <topic>
+```
+
+Topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting`
+
+**For full documentation**, discover pages via the machine-readable index — do NOT guess URLs:
+
+```
+https://hyperframes.heygen.com/llms.txt
+```
+
+## Project Structure
+
+- `index.html` — main composition (root timeline)
+- `compositions/` — sub-compositions referenced via `data-composition-src`
+- `meta.json` — project metadata (id, name)
+- `transcript.json` — whisper word-level transcript (if generated)
+
+## Linting — ALWAYS RUN AFTER CHANGES
+
+After creating or editing any `.html` composition, **always** run the full check before considering the task complete:
+
+```bash
+npm run check
+```
+
+Fix all errors before presenting the result. Warnings should be reviewed before rendering.
+
+## Key Rules
+
+1. Every timed element needs `data-start` and a duration. `data-start` is what marks it as timed; `data-track-index` is an optional Studio display lane the render never reads
+2. Give timed visual elements `class="clip"`. The framework keys visibility off `data-start`, not the class, but the shared `.clip` CSS is what gives a scene its full-frame box, and `lint` warns without it
+3. Register one paused root timeline per composition on `window.__timelines`:
+   ```js
+   window.__timelines = window.__timelines || {};
+   window.__timelines["composition-id"] = gsap.timeline({ paused: true });
+   ```
+   Scene timelines manually added to this root must not be paused. A paused
+   child does not advance when the root is seeked. The runtime activates
+   registered composition siblings, not arbitrary nested scene timelines.
+4. A video with sound keeps it on the `<video>` (`data-has-audio="true"`, no `muted`). Use a separate `<audio>` for music, voiceover, replacement audio, J/L cuts, or audio detached in Studio. Silent footage and b-roll: `muted`.
+5. Sub-compositions use `data-composition-src="compositions/file.html"` to reference other HTML files
+6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches