Skip to content

Commit b0a6571

Browse files
vanceingallsclaude
andcommitted
docs(sdk): address PR review feedback
Correctness fixes from PR #1817 review (Miga + Rames): - types.mdx: FindQuery.text is a substring match (String.includes), not exact - persistence.mdx: import PersistAdapter/PersistVersionEntry/PersistErrorEvent from @hyperframes/sdk (no @hyperframes/sdk/adapters/types export exists) - open-composition.mdx: createHeadlessAdapter is a PreviewAdapter, not a persist adapter; PersistAdapter is exported from @hyperframes/sdk (no /adapters subpath) - types.mdx / adapters.mdx: note KeyframeSpec, ElementAtPointResult, DraftProps are structural shapes, not barrel exports (no import to copy) - overview.mdx: drop leaked authoring meta-comment - timing-and-animation.mdx: getElementTimings is keyed by scopedId - embedded-override-mode.mdx: history is already off by default in embedded mode - editing-affordances.mdx: /editing subpath is merged; soften the version note - querying-and-editing.mdx: bare id only resolves top-level; use find() for sub-composition leaves - canvas-integration.mdx + persistence.mdx: explain the comp closure forward-ref and the fs-adapter subpath (tree-shaking) asymmetry Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 5e842bb commit b0a6571

10 files changed

Lines changed: 19 additions & 10 deletions

‎docs/sdk/guides/canvas-integration.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ const preview = createIframePreviewAdapter(iframe, (op) => {
2828
const comp = await openComposition(compositionHtml, { preview });
2929
```
3030

31+
The callback references `comp` before it is declared — that is intentional and safe: the arrow function captures `comp` by closure and is only ever invoked later (by `commitPreview()` on pointer-up), by which point `comp` is assigned. This is the standard way to break the adapter ⇄ session circular dependency.
32+
3133
The `dispatch` callback is optional. Omitting it means `commitPreview()` is a no-op, which is useful if you want to handle op derivation yourself.
3234

3335
## Hit-testing: finding what the user clicked

‎docs/sdk/guides/editing-affordances.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: "Resolve capability flags and inspector sections for a selected ele
66
`resolveElementAffordances` answers the question "what can the user do with this element right now?" given a live DOM element and its SDK model entry. It returns two objects: `capabilities` (boolean flags for each edit action) and `sections` (which inspector panels apply). You use these to conditionally render controls in your editor's detail panel rather than showing a fixed field set for all elements.
77

88
<Note>
9-
This API ships in hyperframes PR #1814. You need a version of `@hyperframes/sdk` that includes the `/editing` subpath export. Check your installed version before importing.
9+
This API lives on the `@hyperframes/sdk/editing` subpath, added in the editing-affordances change (merged to `main`). It is available in any `@hyperframes/sdk` build cut from `main` after that merge — if the import fails to resolve, upgrade to the latest `0.7.x`.
1010
</Note>
1111

1212
## Import

‎docs/sdk/guides/embedded-override-mode.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ When you read an `OverrideSet` value at a `var.*` key, narrow before treating it
9494

9595
## Disabling SDK undo
9696

97-
In embedded mode the host typically owns the undo stack. Pass `history: false` to skip attaching the SDK's built-in undo module — it keeps the session lightweight and avoids duplicating state:
97+
In embedded mode the host typically owns the undo stack. The SDK already leaves history **off by default** in embedded mode (any session opened with `overrides`), so you usually don't need to do anything. Pass `history: false` explicitly only to make that intent obvious in standalone code paths, or as a guard if a call site may or may not supply `overrides`:
9898

9999
```typescript
100100
const comp = await openComposition(templateHtml, {

‎docs/sdk/guides/persistence.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ const v1Html = await adapter.loadFrom("composition.html", versions[1].key);
8787

8888
Writes to the filesystem and keeps a rolling version history under `.hf-versions/`. Node.js only — do not use in browser builds.
8989

90+
<Note>
91+
`createFsAdapter` is imported from the `@hyperframes/sdk/adapters/fs` **subpath**, not the main barrel like `createMemoryAdapter`. The fs adapter pulls in Node's `fs` module, so keeping it on a separate subpath lets browser bundles tree-shake it away — importing it from the root would drag `node:fs` into a browser build.
92+
</Note>
93+
9094
```typescript
9195
import { createFsAdapter } from "@hyperframes/sdk/adapters/fs";
9296

@@ -147,8 +151,7 @@ export interface PersistAdapter {
147151
**Minimal example — an HTTP / S3-style adapter:**
148152

149153
```typescript
150-
import type { PersistAdapter, PersistVersionEntry } from "@hyperframes/sdk/adapters/types";
151-
import type { PersistErrorEvent } from "@hyperframes/sdk";
154+
import type { PersistAdapter, PersistVersionEntry, PersistErrorEvent } from "@hyperframes/sdk";
152155

153156
export function createHttpAdapter(baseUrl: string): PersistAdapter {
154157
const errorHandlers: Array<(e: PersistErrorEvent) => void> = [];

‎docs/sdk/guides/querying-and-editing.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ if (el) {
4646
}
4747
```
4848

49-
Both bare ids (top-level elements) and scoped ids (sub-composition elements) are accepted.
49+
Both bare ids (top-level elements) and scoped ids (sub-composition elements) are accepted. A bare id resolves only against top-level elements: a leaf that exists **only** inside a sub-composition returns `null` even if its id is unique in the document — use `find()` to discover its scoped form (`"hf-HOST/hf-LEAF"`), then pass that to `getElement`.
5050

5151
### `find(query)`
5252

‎docs/sdk/guides/timing-and-animation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Every clip in a HyperFrames composition has a position on the timeline (`data-st
99

1010
### Reading timings
1111

12-
`getElementTimings()` returns a `Record<HfId, ElementTimingSnapshot>` — one entry per element that carries timing data. Values are derived from the live DOM on every call (never cached in the snapshot).
12+
`getElementTimings()` returns a `Record<HfId, ElementTimingSnapshot>` — one entry per element that carries timing data. Values are derived from the live DOM on every call (never cached in the snapshot). Keys are `scopedId`: for top-level elements this equals the bare `id`, but for elements inside a sub-composition it is the scoped form `"hf-HOST/hf-LEAF"`.
1313

1414
```typescript
1515
import { openComposition } from "@hyperframes/sdk";

‎docs/sdk/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ npm install @hyperframes/sdk
1919

2020
**Adapters decouple persistence and preview.** The SDK never reaches the filesystem or an iframe directly. You supply a `PersistAdapter` (memory, filesystem, S3, HTTP — same interface) and optionally a `PreviewAdapter`. The session fires `persist:error` events on write failures instead of throwing. This makes the SDK equally at home in a Node.js agent, a browser editor, and a CI pipeline.
2121

22-
**Standalone vs embedded mode.** In standalone mode you own the HTML and the SDK owns history and autosave. In embedded (override) mode you supply a base template and a sparse `OverrideSet` delta; the SDK folds the delta onto the template at open time, accumulates further edits into the override set, and lets you store only the delta — the base template stays untouched. Two sentences that cover two completely different deployment patterns.
22+
**Standalone vs embedded mode.** In standalone mode you own the HTML and the SDK owns history and autosave. In embedded (override) mode you supply a base template and a sparse `OverrideSet` delta; the SDK folds the delta onto the template at open time, accumulates further edits into the override set, and lets you store only the delta — the base template stays untouched.
2323

2424
## Guides
2525

‎docs/sdk/reference/adapters.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,10 @@ interface DraftProps {
143143

144144
`dx` and `dy` are the accumulated drag deltas in composition pixels. `width` and `height` are defined in the interface for forward compatibility but are not yet wired to any op.
145145

146+
<Note>
147+
`ElementAtPointResult` and `DraftProps` are the structural shapes a `PreviewAdapter` produces and consumes. They are **not** re-exported from the `@hyperframes/sdk` barrel — you implement against these shapes rather than importing them.
148+
</Note>
149+
146150
---
147151

148152
## Factory Functions

‎docs/sdk/reference/open-composition.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The same function covers three deployment patterns. Which mode you get depends e
3737
<ParamField path="persist" type="PersistAdapter">
3838
Storage adapter for autosave. After every committed change the SDK enqueues a write to this adapter. The session fires `persist:error` events instead of throwing on write failures.
3939
40-
Built-in adapters: `createMemoryAdapter()` (tests/demos), `createFsAdapter()` (Node.js), `createHeadlessAdapter()` (no-op). Custom adapters implement the `PersistAdapter` interface from `@hyperframes/sdk/adapters`.
40+
Built-in adapters: `createMemoryAdapter()` (tests/demos) and `createFsAdapter()` (Node.js). Custom adapters implement the `PersistAdapter` interface, exported from `@hyperframes/sdk`. (`createHeadlessAdapter()` is a `PreviewAdapter` for the `preview` field below — not a persist adapter.)
4141
4242
See the [persistence guide](/sdk/guides/persistence) for adapter selection and configuration.
4343
</ParamField>

‎docs/sdk/reference/types.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ interface FindQuery {
205205
</ResponseField>
206206

207207
<ResponseField name="text" type="string">
208-
Match by the element's direct text content (exact string match).
208+
Match by the element's direct text content (case-sensitive substring match — implemented with `String.includes`).
209209
</ResponseField>
210210

211211
<ResponseField name="name" type="string">
@@ -295,7 +295,7 @@ interface GsapTweenSpec {
295295

296296
## KeyframeSpec
297297

298-
A single keyframe entry for `addWithKeyframes` and `replaceWithKeyframes`.
298+
A single keyframe entry for `addWithKeyframes` and `replaceWithKeyframes`. This is a structural shape, not a runtime export — you pass plain objects of this form to those methods; it is **not** re-exported from the `@hyperframes/sdk` barrel, so there is nothing to import.
299299

300300
```typescript
301301
interface KeyframeSpec {

0 commit comments

Comments
 (0)