chore: import upstream snapshot with attribution

docs/packages/sdk.mdx

@@ -0,0 +1,227 @@
+---
+title: "@hyperframes/sdk"
+description: "Headless, framework-neutral composition editing engine for agents and custom editors."
+---
+
+The SDK package provides a programmatic editing layer for HyperFrames compositions. It opens composition HTML, exposes query and mutation APIs, emits JSON patches, supports undo/redo, and can persist changes through pluggable adapters without requiring React, Studio, or a browser UI.
+
+```bash
+npm install @hyperframes/sdk
+```
+
+## When to Use
+
+**Use `@hyperframes/sdk` when you need to:**
+- Build a custom composition editor in your own application
+- Let an agent inspect and edit composition HTML without driving a browser UI
+- Apply batch text, style, timing, asset, variable, or animation edits from code
+- Track undo/redo and patch events for host application history
+- Persist edited HTML through memory, filesystem, or custom storage adapters
+- Layer sparse overrides on top of a reusable base composition template
+
+**Use a different package if you want to:**
+- Render compositions to MP4 or WebM - use the [CLI](/packages/cli) or [producer](/packages/producer)
+- Preview and edit visually out of the box - use the [CLI](/packages/cli) (`npx hyperframes preview`) or [studio](/packages/studio)
+- Parse, lint, or generate low-level composition HTML - use [core](/packages/core)
+- Capture frames from a headless browser - use [engine](/packages/engine)
+
+<Tip>
+  The SDK is the right layer for product integrations and agents that need structured edits. The CLI and Studio are user-facing tools built around the same composition format; the SDK is the editing engine you embed behind your own UI or automation.
+</Tip>
+
+<Note>
+  This page is the package overview. For the full API — guides and a complete reference for every method, operation, type, and adapter — see the [**SDK**](/sdk/overview) tab.
+</Note>
+
+## Package Exports
+
+| Import | Description |
+|--------|-------------|
+| `@hyperframes/sdk` | Main editing API, types, memory/headless adapters, iframe preview adapter |
+| `@hyperframes/sdk/adapters/memory` | In-memory persistence adapter for tests, demos, and ephemeral sessions |
+| `@hyperframes/sdk/adapters/fs` | Node.js filesystem persistence adapter with version history |
+| `@hyperframes/sdk/adapters/headless` | No-op preview adapter for agents, CI, and server-side editing |
+
+## Quick Start
+
+Open HTML, edit explicit element IDs, then serialize the updated composition:
+
+```typescript
+import { openComposition } from "@hyperframes/sdk";
+
+const comp = await openComposition(html);
+
+const [headlineId] = comp.find({ text: "Old headline" });
+if (headlineId) {
+  comp.setText(headlineId, "New headline");
+  comp.setStyle(headlineId, {
+    color: "#FFD60A",
+    fontSize: "96px",
+  });
+}
+
+const updatedHtml = comp.serialize();
+comp.dispose();
+```
+
+## Core Concepts
+
+### Explicit Element IDs
+
+All edits target stable HyperFrames element IDs. This makes the SDK safe for headless agents and backend jobs because mutations do not depend on mouse state or a current UI selection.
+
+```typescript
+const allElements = comp.getElements();
+const imageIds = allElements
+  .filter((element) => element.tag === "img")
+  .map((element) => element.id);
+
+for (const id of imageIds) {
+  comp.setAttribute(id, "loading", "eager");
+}
+```
+
+### Typed Methods
+
+The common editing operations have typed convenience methods:
+
+```typescript
+comp.setText("hf-title", "Launch day");
+comp.setStyle("hf-title", { color: "#ffffff", transform: "translateY(24px)" });
+comp.setAttribute("hf-logo", "src", "/assets/logo.png");
+comp.setTiming("hf-title", { start: 0.5, duration: 2.5 });
+comp.setVariableValue("brandColor", "#6C5CE7");
+comp.removeElement("hf-old-caption");
+```
+
+Use `batch()` when several mutations should become one undo entry, one persist write, and one change notification:
+
+```typescript
+comp.batch(() => {
+  comp.setText("hf-title", "Version 2");
+  comp.setStyle("hf-title", { color: "#22C55E" });
+  comp.setTiming("hf-title", { start: 1, duration: 3 });
+});
+```
+
+### Advanced Dispatch API
+
+Agents and automation can emit data-shaped operations through `dispatch()`:
+
+```typescript
+comp.dispatch({
+  type: "setStyle",
+  target: "hf-card",
+  styles: { borderRadius: "24px" },
+});
+```
+
+Before showing a UI control or applying an optional operation, call `can()`:
+
+```typescript
+const result = comp.can({
+  type: "setGsapTween",
+  animationId: "anim-1",
+  properties: { ease: "power3.out" },
+});
+
+if (result.ok) {
+  comp.setGsapTween("anim-1", { ease: "power3.out" });
+}
+```
+
+## Persistence
+
+Pass a persistence adapter to autosave edits. The SDK ships memory and filesystem adapters, and host applications can implement the same `PersistAdapter` interface for S3, HTTP, IndexedDB, or app-specific storage.
+
+```typescript
+import { openComposition } from "@hyperframes/sdk";
+import { createFsAdapter } from "@hyperframes/sdk/adapters/fs";
+
+const comp = await openComposition(html, {
+  persist: createFsAdapter({ root: "./project" }),
+  persistPath: "index.html",
+});
+
+comp.setText("hf-title", "Saved title");
+await comp.flush();
+```
+
+Persistence failures are emitted as events instead of crashing the session:
+
+```typescript
+comp.on("persist:error", ({ error }) => {
+  console.error("Autosave failed:", error.message);
+});
+```
+
+## Undo, Redo, and Patch Events
+
+Standalone sessions include undo/redo by default:
+
+```typescript
+comp.setText("hf-title", "Draft");
+comp.undo();
+comp.redo();
+```
+
+Patch events let a host application mirror SDK edits into its own state, collaboration layer, or audit log:
+
+```typescript
+const unsubscribe = comp.on("patch", ({ patches, inversePatches, origin }) => {
+  saveToHostHistory({ patches, inversePatches, origin });
+});
+
+unsubscribe();
+```
+
+## Embedded Override Mode
+
+For template-driven products, open a composition with an `overrides` object. The SDK applies the sparse override set on top of the base HTML, accumulates additional edits into that override set, and lets the host store only the delta.
+
+```typescript
+const comp = await openComposition(templateHtml, {
+  overrides: {
+    "hf-title.text": "Customer-specific title",
+    "hf-logo.attr.src": "/customers/acme/logo.png",
+  },
+  history: false,
+});
+
+comp.setStyle("hf-title", { color: "#0EA5E9" });
+
+const nextOverrides = comp.getOverrides();
+```
+
+Use `applyPatches()` when the host owns undo/redo and needs to replay inverse patches into the SDK without creating loops.
+
+## Preview Adapters
+
+The SDK can run headlessly, or it can connect to a preview surface:
+
+```typescript
+import { openComposition, createHeadlessAdapter } from "@hyperframes/sdk";
+
+const comp = await openComposition(html, {
+  preview: createHeadlessAdapter(),
+});
+```
+
+For browser integrations, `createIframePreviewAdapter()` bridges the SDK to a same-origin composition iframe so hit-testing, selection, and draft preview updates can stay outside the model mutation path.
+
+## Related Packages
+
+<CardGroup cols={2}>
+  <Card title="@hyperframes/core" icon="cube" href="/packages/core">
+    Low-level types, HTML utilities, runtime helpers, and linter APIs.
+  </Card>
+  <Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
+    Ready-made visual editor UI that can embed SDK-driven editing flows.
+  </Card>
+  <Card title="@hyperframes/producer" icon="video" href="/packages/producer">
+    Programmatic rendering pipeline for turning edited HTML into video.
+  </Card>
+  <Card title="CLI" icon="terminal" href="/packages/cli">
+    Command-line create, preview, lint, and render workflows.
+  </Card>
+</CardGroup>