stillmade-sdk 0.1.41 → 0.1.43

package/docs/reference/universal-resolver.md

@@ -0,0 +1,303 @@
+# Universal requirement resolver
+
+# Universal requirement resolver
+
+The public SDK exports `createUniversalResolver()`, the same implementation used
+by the Project Type composer, runtime input resolution and native explanations.
+The older `block-platform/universal-resolver.js` import reexports this engine.
+
+### Interactive JavaScript user requests
+
+The Node SDK host may explicitly provide `runPackageAsync(..., {requestFromUser})`.
+An isolated Block can return `StillMade.requestFromUser('name')` for a missing,
+optional, non-context input whose contract allows user answers. Check
+`StillMade.resolveRequirement('name').resolved` first. The SDK resumes the code
+from its beginning with the validated answer in `input.name`; this is a
+cooperative return, not a Promise or an in-sandbox host callback. Avoid emitting
+outputs before returning the request. Other inputs remain unchanged.
+
+Both worker boundaries validate the exact declared question and answer. Questions
+cannot collect credentials, overwrite existing values, widen permissions, or call
+providers. At most 20 questions are allowed. The Node worker pauses its cumulative
+five-second execution allowance while waiting, with a five-minute answer deadline;
+the guest's cumulative CPU and memory limits remain in force. Cancellation ends the
+run. Successful results include `userAnswers` for the host to persist alongside
+execution provenance. Hosts without the callback fail closed.
+
+The application browser runner enables this bridge for individual non-batch
+JavaScript Step runs. It rechecks project identity, edit access, source admission,
+and the captured input snapshot around each question. Reviewed answers become
+semantic user values and contribute to the accepted run's input digest and output
+dependencies. Other browser callers must explicitly supply both a question handler
+and a current-project guard; otherwise interactive requests remain unavailable.
+Browser execution pauses its cumulative worker allowance during a bounded question
+wait, without expanding the guest CPU allowance. Batch
+questions, automatic in-run Chat, and shared credit accounting remain unfinished.
+
+Interactive connected local runs now also forward user requests for JavaScript
+Steps with stop-on-error, bounded retry, or approval-before-retry policies, including connected media batches. The workflow
+runner independently validates each question, captures the reviewed answer, and
+requires the executor to return exactly those answers. The accepted input digest
+includes them, and retained results restore/revalidate optional answers without
+opening dialogs or rerunning completed Steps. Connected job deadlines still apply;
+fallback/recovery policies and unattended runs do not enable these questions.
+Retries receive previously reviewed answers as existing inputs instead of asking
+again. Each attempt may return only answers newly reviewed during that attempt;
+the workflow retains the aggregate and binds it to the successful result. Late
+replies from an ended attempt cannot change the retained answer set.
+
+Connected batch questions name the current source asset and version. Answers are
+scoped to that target's run and do not silently carry into the next target. Resume
+validation binds them to the full source snapshot as well as the package, workflow,
+and effective inputs. Standalone single-Step batch previews also enable questions.
+Each preview keeps its own reviewed answers and input fingerprint. Using a result
+rechecks source, settings and answers, then registers the selected answers and
+outputs as the adopted single-Step result. Previews alone do not overwrite saved
+answers or advance saved Block memory.
+
+Structured collections use a one-element schema array, such as
+`schema: [{word: 'string', start: 'number', end: 'number'}]` on an `object[]`
+contract. That schema describes every item, not a tuple or a fixed-length value.
+It also works inside object fields. Validation and connection compatibility check
+each item's required fields; plain `object[]` cannot promise those fields.
+The input dialog collects structured list items using their declared fields.
+
+Built-in connection adapters also support ordered lists when both endpoints are
+scalar types with list variants. Each list adapter pins the scalar adapter version,
+converts at most 100 items, checks each item, and requires all context grants before
+conversion. A failed item rejects the entire conversion; no partial list is emitted.
+List-to-scalar flattening, implicit Block fan-out, and nested lists are not inferred.
+For example, `text[]` with meaning `narration_script` can supply `script[]` with the
+same meaning through `list-text-to-script-v1` version 1. These are local data
+conversions, not separately billed provider calls or general workflow batches.
+
+```js
+import {createUniversalResolver,input} from './packages/block-sdk/index.js';
+
+const requirement=input({
+  key:'company',type:'object',semantic:'company_profile',required:true,
+  description:'Company information',schema:{name:'string'},sources:['project']
+});
+const resolver=createUniversalResolver();
+const options={values:[{
+  id:'company-profile',revision:1,type:'object',semantic:'company_profile',
+  value:{name:'Morning Bakery'},source:{kind:'project'},permissions:[]
+}]};
+const explanation=resolver.inspect(requirement,options);
+const resolved=await resolver.resolve(requirement,options);
+```
+
+`inspect` and `explain` return the selected source, reason and candidates.
+`listCandidates` returns priority-ordered alternatives. `resolve` checks actual
+values and returns source/dependency metadata. A required unresolved input stays
+unresolved; a pending callback can return one clarification question.
+
+Pass an explicit semantic registry and versioned adapter registry when needed.
+The host may supply `canDerive`, `requestFromChat` and `requestFromUser` callbacks.
+No callback is provided automatically. Permission and freshness filtering applies
+to context passed to those callbacks; source/schema validation still applies to
+their results. Use stable record IDs and revisions for executable values. Plan
+mode can inspect declarations that do not yet contain a value; `resolve` always
+requires materialized values or an answer callback.
+
+Callbacks receive isolated copies. Final resolution rechecks dependency freshness
+after waiting for an answer and rejects expired sources or missing revisions.
+The host must still detect edits to the underlying project while resolving; a
+copied context snapshot does not subscribe to storage changes.
+
+This is a trusted-host/authoring library, not a new guest API or permission grant.
+It does not fetch project data, mutate projects, run Blocks, approve purchases,
+authorize credentials, or enforce a provider spending budget. Hosts must retain
+their existing scoped storage, sandbox, approval, cancellation and shared-budget
+boundaries around integrations. Do not register arbitrary creator code as a host
+callback. Download assembly includes this module, but generated download artifacts
+must be rebuilt separately.
+# Custom meanings and connection checks
+
+Pass the same explicit `semantics` registry to the universal resolver and to
+`compatible`, `connectionCompatibility`, `validateConnectionAdapter` and
+`adaptConnectionValue`. The optional argument is `{semantics}`; adapter calls
+retain their existing permission, context and exact-version pin options.
+Inheritance widens only meaning compatibility, never physical types, schemas,
+permissions or adapter versions. Without a registry, only the standard semantic
+relationships apply. No process-global registry is mutated by these calls.
+
+The application composition helpers accept the same scoped registry for audits,
+automatic connection selection, explicit source selection and recommendation
+checks. Store reusable definitions in `manifest.semantics`:
+
+```js
+semantics: [{
+  name: 'creator.example.spoken_copy',
+  description: 'Words to read aloud.',
+  parents: ['narration_script']
+}]
+```
+
+Each Block may declare up to 64 namespaced meanings, eight parents per meaning
+and 500 description characters. Definitions cannot override unnamespaced standard
+meanings. Duplicate names within a Block, cycles, and conflicting parent sets
+across selected versions are rejected. Matching definitions may be shared.
+The source and release digest includes these declarations; changing a published
+definition requires a new release, not editing an immutable version.
+
+`semanticRegistryForManifests(manifests)` reconstructs a scoped registry from
+saved contracts. Composer audits and local workflow execution load these package
+definitions automatically. Connected execution captures their exact snapshot in
+the execution-plan digest. Explicit injected registries are still ephemeral;
+only package declarations survive save/reopen. Guest access to arbitrary project
+context, generated adapter execution and automatic metered Chat derivation are
+separate integrations, not permissions granted by declaring a meaning.
+
+## Direct structured answers
+
+The application's reviewed-answer dialogs collect required schema fields with
+typed controls, leaving optional fields unasked and preserving existing optional
+answers during edits. Unstructured objects offer named details with text,
+number, yes/no, nested-detail, list and empty-value choices. Object and JSON
+lists support adding, editing and removing items without requiring JSON syntax.
+Primitive schemas on JSON inputs choose the corresponding typed question.
+
+These dialogs serve the existing lazy user resolver, shared-default editor and
+connected preview samples. They capture the contract and previous answer before
+waiting, validate the final value and return nothing on cancellation. Collection
+is bounded to 20 recursive questions, 60 menu choices, 20 detailed list items or
+object fields, and the existing 8,000-character scalar/simple-list limits. Larger
+answers still need the appropriate settings editor. Source permissions and
+credential restrictions remain enforced by the calling resolver; these controls
+do not create new runtime authority or automatically invoke Chat.
+
+Single-Step and connected-run missing-answer collection use the same universal
+resolver for allowed defaults and user callbacks. A permitted default is selected
+before asking; it is not recorded as a user answer. Retained reviewed answers
+remain explicit replay inputs. Contract, supplied-input and retained-answer
+snapshots are captured before waiting, and callbacks cannot claim dependencies on
+unavailable context. Existing host scope checks still reject edits to the real
+project during collection. This does not enable automatic paid Chat calls.
+
+## Versioned document conversions
+
+The shared connection registry includes `csv-file-to-table@1`,
+`text-to-script@1` and `script-to-text@1`. Visual/native composition, explicit
+connection pins and semantic context resolution use the same descriptors.
+
+CSV files must be single inline `.csv` files declared with the `csv` meaning;
+the result has the `table` meaning and `{columns, rows}` schema. Archives,
+remote media and malformed CSV are rejected. The existing CSV limits and
+string-preserving parser apply; cell contents are never executed.
+
+Script conversions preserve semantic compatibility and exact words. Wrapping
+adds only `{schemaVersion: 1, text}`; unwrapping requires readable `text` and
+does not carry other script metadata into the text output. Neither conversion
+turns research notes into narration or invents additional required fields.
+Candidate checks validate actual values when present. Version pins, source
+policy, inherited permissions and provenance remain enforced. These are
+deterministic built-ins, not arbitrary multi-hop or creator-code adapters.
+
+## Conditional SDK Steps
+
+Existing Step conditions support `greater-than`, `at-least`, `less-than` and
+`at-most` in addition to presence and equality comparisons. Numeric thresholds
+must be finite numbers; missing values, strings and booleans do not satisfy a
+numeric comparison. Safe field paths and existing default handling still apply.
+The builder and native `set_condition` control share `setProjectTypeCondition`;
+use `null` to remove a condition. Native Step inspection includes its condition.
+
+These conditions retain the existing false-case behavior: pass the primary input
+unchanged to a single compatible output. They do not create general branches,
+invent outputs, enable hosted-workspace conditions or grant execution approval.
+
+Reviewed Chat suggestions share `canSuggestRequirement` eligibility across the
+application and server. Supported information includes scalar text/numbers/
+booleans, script documents, objects, JSON and their supported lists. Host-bound
+context, credential-sensitive inputs and inputs excluding Chat remain ineligible.
+The server captures the notes and requirement before waiting and validates the
+returned value before issuing matching provenance. This remains a reviewed
+suggestion, not automatic workflow dispatch or a budget authorization.
+
+## Saved-project source updates
+
+Project Type connections use the Block's declared input and output contracts,
+including Blocks a creator adds later. A reviewed source change updates that
+project's binding and marks affected results stale; it does not run a Block.
+An explicit affected-Step update can then reuse a current saved upstream value.
+The runner pins that value before dispatch and records its producer placement,
+output port and run ID in the receiving run's captured input identities. The
+pin is checked again during execution, so a changed upstream result requires a
+fresh review. Text and structured input contents are not copied into this
+identity record; inspect the authorized value separately when needed.
+
+## Recommendation execution evidence
+
+The hosted completion signal uses server-owned, terminal production capability
+runs for an exact public release digest over 30 days. It excludes creator
+self-use, suspended accounts, revoked releases, previews, cancellation and
+unresolved remote work. At least five terminal runs from three users are needed;
+each user contributes at most 20 recent runs per release. A smoothed completion
+adjustment between minus two and plus two points supplements, but cannot replace, capability coverage
+and connection validation. Creator-supplied quality numbers are not used.
+
+This signal measures terminal execution completion, not generated-content
+quality, local execution reliability or resistance to coordinated account abuse.
+Missing evidence contributes no adjustment and does not mean failure. A measured
+completion rate below one half lowers ranking rather than earning a bonus; a
+rate of one half is neutral. The response
+reports signal availability and the number of measured releases. Cost, latency
+and creator reputation remain unmeasured ranking signals.
+
+Visual recommendation Details explains these limits and measured-Block coverage.
+Native recommendation inspection includes the same signal availability and
+warnings, alongside per-proposal score explanations.
+
+## Guest workspace patch proposals
+
+JavaScript Blocks can call
+`StillMade.patchProject(outputKey, {field, title, after})` to emit a reviewed
+workspace-edit proposal. Declare a `workspace-edit` output, a matching context
+input, and both `context.<field>.read` and `workspace.<field>.propose` permissions.
+The helper obtains `before` from the original host-supplied context snapshot,
+not the guest's mutable input. It returns no value and uses the ordinary output
+collector: emit each output once and do not also return an output object.
+
+This method does **not** apply an edit, save a project, grant permissions or call
+the host from the sandbox. Final outputs pass the existing workspace-edit and
+permission validators; the host's review and stale-document checks still decide
+whether a proposal can be applied. Only existing workspace-edit fields are
+supported, not arbitrary project fields or credentials. Guest Chat/user request
+bridges and broader project mutation remain separate unfinished integrations.
+
+## Bounded adapter paths
+
+### Creator-owned conversion Blocks
+
+When two admitted Blocks declare incompatible inputs and outputs, the Project
+Type builder can search saved Blocks for a real intermediate Step. **Find
+converter Blocks** inspects each candidate's versioned ports and source policy;
+it does not run the candidate or infer that its result is correct. Choosing one
+embeds the exact package version and creates two ordinary typed connections.
+The connected runner executes the intermediate Block through its declared
+runtime and validates its output before the receiver runs. Saved-project Flow
+can search converter packages already embedded in that Project Type and review
+the migration before adding an instance. This route preserves each Block's own
+implementation and does not install a creator's transform in the trusted host.
+
+The on-demand search discovers paths of up to three intermediate Blocks with
+bounded exploration. Longer routes can still be composed as ordinary Steps.
+New Marketplace package search from an existing project and full native/hosted
+acceptance are still required for general interoperability. A source preview in
+the search is never presented as a converter's unrun output.
+
+Trusted resolver callers can opt into `maxAdapterHops: 2` or `3`. The default
+remains one for compatibility with existing saved connection pins. Registries
+expose `findPaths(source, requirement, options)` and
+`applyPath([{id, version}, ...], source, requirement, options)`. Search uses
+contract compatibility without executing transforms, examines at most 512
+edges and returns at most 16 paths. `inspect` reports `searchTruncated` when
+those limits prevent an exhaustive search.
+
+Execution preflights the complete chain's permissions and contracts, validates
+each intermediate result, preserves the original source's freshness and returns
+provenance containing every conversion pin plus the original source revision.
+These are trusted registered adapters, not creator-code execution authority.
+Saving and executing chain pins in the visual/native application is not yet
+integrated; existing connection paths remain unchanged.

package/docs/reference/view-bridge.md

@@ -0,0 +1,60 @@
+# Interface bridge reference
+
+Standard and frame views receive the same `StillMade` object; members marked Frame views exist only there. `In` and `Out` are the Block's input and output values (see [TypeScript](../build/typescript.md)). The view host checks every request itself: a read-only viewer cannot run the Block or save outputs from any view.
+
+### Inputs and runs
+
+| Member | Where | What it does |
+| --- | --- | --- |
+| `readonly input: Partial<In>` | Every view | A copy of the current input values. Read it after `onInput` first fires. |
+| `onInput(callback: (input: Partial<In>) => void): () => void` | Every view | Receives the input when the view starts and each time the host changes it. Returns a function that stops listening. Initialize controls here. |
+| `addFiles(port: string): Promise<{added: number}>` | A saved project Step and the SDK preview | Opens StillMade's own file picker for a declared `image`, `video`, `audio`, `asset` or `file` input (or a list of them) and saves what the person chooses through StillMade's upload, as the Step's own tiles do. Call it from a click or key press in the view; a list gets the files added, a single input the first. The saved values arrive through `onInput`; the view never receives a File. A `<button class="sm-add" data-stillmade-add="port">` does this with no code. Refused for an undeclared or non-file input, an input an earlier Step fills, a viewer, and without a gesture. |
+| `removeFile(port: string, index: number): Promise<{files: number}>` | A saved project Step and the SDK preview | Removes the file at `index` (from 0) of a declared list input (`image[]`, `video[]`, `audio[]`, `asset[]` or `file[]`), as the remove button on the Step's own tile does, and resolves to how many files the list now holds. Call it from a click or key press in the view; the new list arrives through `onInput`. A `<button data-stillmade-remove="port" data-index="2">` does this with no code. Refused for an undeclared, non-file or single input, an input an earlier Step fills, a viewer, Chat, a file that changed since the view was given it, and without a gesture. |
+| `moveFile(port: string, from: number, to: number): Promise<{files: number}>` | A saved project Step and the SDK preview | Moves the file at `from` to the place `to` (both from 0) in a declared list input, as the Step's own move earlier and move later buttons do, so the person sets the order (a tour, a slideshow) on the Block's own screen. Same gesture and refusals as `removeFile`. A `<button data-stillmade-move="port" data-index="2" data-to="1">` does this with no code; a `data-to` past either end does nothing. |
+| `run(values: In): Promise<Out>` | Every view | Checks the named input values, runs the Block (its recipe, JavaScript, module or hosted operation, after any approval the host asks for) and resolves to the checked outputs. On a project Step and in the SDK preview, inputs it leaves out run with the Step's current values (its photos, an earlier Step's result), so a view passes only what it sets; what it passes is kept as the Step's input. One run at a time, 30 a minute. |
+| `useOutput(outputs: Partial<Out>): Promise<Record<string, unknown>>` | A saved project Step | Chooses media the view already holds (input media or a desktop recording) as the Block outputs without running. Only complete references the host issued are accepted. |
+| `readonly schemaFields: Readonly<Record<string, unknown>>` | Every view | Helpers that build form fields from the input ports and their schemas, honoring inputs the host locked. |
+
+### Shared state
+
+| Member | Where | What it does |
+| --- | --- | --- |
+| `getShared(): {state: Record<string, unknown>; outputs: Record<string, unknown>; memory: unknown; canEdit: boolean}` | Every view | A copy of the view state shared by everyone in the project, the last outputs, the Block memory and whether this person may edit. |
+| `onShared(callback: (shared: ReturnType<StillMadeView["getShared"]>) => void): () => void` | Every view | Receives the shared state now and after every change by anyone. Returns a function that stops listening. |
+| `updateShared(values: Record<string, unknown>, preconditions?: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>` | Every view | Changes shared fields. Keep each independently edited value in its own field so two people never conflict; a field someone else changed first is refused. |
+| `bindShared(key: string, id: string): () => void` | Every view | Binds a form element (by id) to one shared field: it shows other people's edits and saves this person's edits, keeping drafts while they type. |
+| `setSharedDefaults(values: Record<string, unknown>): void` | Every view | Values bound controls show until someone saves the field. |
+| `scheduleSharedEdit(key: string, callback: () => unknown \| Promise<unknown>): void` | Every view | Runs a named shared edit after a short pause (at most 500 ms after the first request), so rapid edits to one field (sliders, drags) become one save. |
+| `connectDocument(options: Record<string, unknown>): Readonly<Record<string, unknown>>` | Every view | Connects a declared JSON content store to shared edits once; returns its status, flush and recovery methods. |
+| `indexById(items: Array<{id: string; [key: string]: unknown}>): Map<string, {id: string; [key: string]: unknown}>` | Every view | Indexes list items by their stable id. |
+| `diffDocument(before: Record<string, unknown>, after: Record<string, unknown>): Array<Record<string, unknown>>` | Every view | The minimal list of edits between two versions of a document. |
+| `applyDocument(document: Record<string, unknown>, patches: Array<Record<string, unknown>>): Record<string, unknown>` | Every view | Applies edits from diffDocument to a document. |
+
+### Media
+
+| Member | Where | What it does |
+| --- | --- | --- |
+| `previewImage(value: StillMadeImage): Promise<{url: string; width: number; height: number}>` | Every view | A display-only PNG copy (at most 512 pixels a side) of an image the view may show. Keep passing the original value to run. |
+| `previewMedia(value: StillMadeVideo \| StillMadeAudio): Promise<{kind: "video" \| "audio"; url: string}>` | Every view | A playable blob: URL for audio or video the view may play. Call releaseMedia when done. |
+| `releaseMedia(url: string): void` | Every view | Frees a URL previewMedia returned. |
+| `asset(path: string): string` | Frame views | A blob: URL for one of the view's own asset files, for <img>, new FontFace() or <video>. |
+| `readonly live: {start(options: {camera?: boolean; microphone?: boolean; fps?: number; width?: number; sampleRate?: number}): Promise<{live: true; camera: boolean; microphone: boolean; fps: number; width: number; height: number; sampleRate: number}>; stop(): Promise<{live: false}>; status(): Promise<{live: boolean; [key: string]: unknown}>; onFrame(callback: (frame: ImageBitmap, info: {index: number; timestamp: number; width: number; height: number}) => void): () => void; onAudio(callback: (samples: Float32Array, info: {index: number; timestamp: number; sampleRate: number}) => void): () => void; onEnd(callback: (event: {reason: string}) => void): () => void}` | Every view | The camera, the microphone or both as they happen (declare camera.capture and microphone.capture). Nothing reaches the view until the person presses Start in StillMade, which then shows that the device is on and a Turn off button. Frames arrive as ImageBitmaps, closed when your callback returns, so draw or copy them there; a slow view gets fewer frames, never a backlog. Audio arrives as mono Float32Array chunks. Nothing is saved. In browsers and StillMade Desktop. |
+| `assetBytes(path: string): ArrayBuffer` | Frame views | A copy of one of the view's own asset files. |
+
+### Generated interface
+
+| Member | Where | What it does |
+| --- | --- | --- |
+| `render(targetId: string, tree: Array<Record<string, unknown>>): void` | Every view | Renders a tree of StillMade controls into an element, for standard views that build their interface from data. |
+| `onAction(callback: (event: {action: string; value: unknown; checked: boolean; event: string}) => void \| Promise<void>): () => void` | Every view | Receives actions from controls render drew. |
+
+### Connected work
+
+| Member | Where | What it does |
+| --- | --- | --- |
+| `connectedApp(operation: "tasks" \| "preview-task" \| "apply-task", args?: Record<string, unknown>): Promise<Record<string, unknown>>` | A saved project Step | Lists, previews and applies tasks of the Block's connected-app contract. |
+| `sharedWork(operation: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>` | A saved project Step | Reads and contributes to shared work items (reviews, contributions) in the project. |
+| `onSharedWorkRefresh(callback: () => void): () => void` | A saved project Step | Called when shared work changes elsewhere; read it again. |
+| `previewSharedWorkMedia(contributionId: string): Promise<{url: string; kind: "image" \| "video" \| "audio"}>` | A saved project Step | A display copy of media attached to a shared work contribution. |
+| `releaseSharedWorkMedia(url: string): void` | A saved project Step | Frees a URL previewSharedWorkMedia returned. |
+| `desktop(operation: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>` | Every view for recording and folders; StillMade Desktop for the rest | Runs a declared desktop permission after the person grants it. Recording (record.start, record.stop, record.cancel, record.status), cutting a recording (record.cut) and folders the person picks (folder.*; Chrome and Edge in a browser) work in browsers and in StillMade Desktop; clipboard, media.pick, notifications, keep-awake and native tools need StillMade Desktop. Picking or pressing Start is the consent; StillMade asks once only about the clipboard, the cursor and desktop programs. |

package/docs/reference/view-rules.md

@@ -0,0 +1,15 @@
+# Custom view rules
+
+## Custom view rules
+Standard custom view code (no `view.config.json` frame runtime) is checked before it runs. These rules come straight from the validator; frame views run in their own sandbox and may build the page with ordinary DOM calls such as `createElement`:
+
+- **HTML elements:** only `div`, `section`, `article`, `header`, `footer`, `main`, `aside`, `nav`, `h1`, `h2`, `h3`, `h4`, `p`, `span`, `strong`, `em`, `i`, `small`, `br`, `hr`, `label`, `input`, `textarea`, `button`, `select`, `option`, `optgroup`, `fieldset`, `legend`, `output`, `progress`, `meter`, `ul`, `ol`, `li`, `dl`, `dt`, `dd`, `figure`, `figcaption`, `img`, `video`, `audio`, `source`, `canvas`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `pre`, `code`, `details`, `summary`. No scripts, iframes, SVG, forms, comments or inline event attributes; media URLs must be `data:` or `blob:`.
+- **No loops and no function declarations:** view JavaScript may not contain `import()`, `import`, `with`, `this`, `import.meta`/`new.target`, `while`, `do`/`while`, `for`, `for…in`, `for…of`, `function` declarations. Iterate with array `map`/`forEach`/`filter`/`reduce` and write helpers as `const name = (...) => ...`.
+- **Never use these names in view JavaScript, not even for your own variables:** `eval`, `Function`, `AsyncFunction`, `GeneratorFunction`, `require`, `importScripts`, `process`, `globalThis`, `window`, `self`, `top`, `parent`, `opener`, `frames`, `location`, `navigation`, `history`, `navigator`, `localStorage`, `sessionStorage`, `indexedDB`, `caches`, `cookieStore`, `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `Worker`, `SharedWorker`, `ServiceWorker`, `WebAssembly`, `Deno`, `Bun`, `Reflect`, `Proxy`, `DOMParser`, `MutationObserver`, `postMessage`, `open`, `close`, `print`, `alert`, `confirm`, `prompt`, `setInterval`, `setTimeout`, `queueMicrotask`, `arguments`, `constructor`, `__proto__`, `prototype`, `__lookupGetter__`, `__lookupSetter__`, `__defineGetter__`, `__defineSetter__`, `getPrototypeOf`, `setPrototypeOf`, `getOwnPropertyDescriptor`, `getOwnPropertyDescriptors`, `getOwnPropertyNames`, `getOwnPropertySymbols`, `defineProperty`, `defineProperties`, `defaultView`, `ownerGlobal`, `contentWindow`, `contentDocument`, `cookie`, `domain`, `documentURI`, `URL`, `baseURI`, `referrer`, `write`, `writeln`, `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `createElement`, `createElementNS`, `createContextualFragment`, `createRange`, `setAttribute`, `setAttributeNS`, `attributes`, `attributeStyleMap`, `adoptNode`, `importNode`, `execCommand`, `replaceChildren`, `setHTML`, `setHTMLUnsafe`, `parseHTML`, `parseHTMLUnsafe`, `showSaveFilePicker`, `showDirectoryPicker`, `saveAs`, `FileSystemWritableFileStream`, `createWritable`, `msSaveBlob`, `msSaveOrOpenBlob`, `download`.
+- **Never use these property names:** `assign`, `values`, `entries`, `fromEntries` (so no `Object.assign`, `Object.values`, `Object.entries`, `Object.fromEntries`; use arrays and `map`/`forEach`).
+- **These words may not appear anywhere in view JavaScript, even in strings or comments:** `style`, `cssText`, `setProperty`, `removeProperty`, `insertRule`, `deleteRule`, `styleSheets`, `adoptedStyleSheets`, `animate`. Change appearance with CSS classes and `hidden`; put colors in the stylesheet.
+- **Property access with brackets needs a literal key:** `items[0]` and `record["title"]` are accepted; `items[index]` is rejected. Iterate with `map`/`forEach` or call `items.at(index)`.
+- **No named recursive functions** and no listeners on the global frame; attach events to declared controls.
+- **Dynamic elements:** `StillMade.render` can create `div`, `section`, `article`, `header`, `footer`, `p`, `span`, `strong`, `em`, `i`, `small`, `h1`, `h2`, `h3`, `h4`, `label`, `button`, `input`, `textarea`, `select`, `option`, `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `details`, `summary`, `output`, `progress`, `img`; give repeated items stable IDs derived from their identity. An `img` gets its picture when you set its `src` to the data URL `StillMade.previewImage` returns, after rendering; the renderer keeps Block-owned `src`. `previewImage` works on items of an `image[]` input.
+- **Shared writes are queued in order:** if one `StillMade.updateShared` write is rejected (conflict, read-only or timeout), the writes queued behind it are rejected too. Send dependent edits one at a time or through `StillMade.scheduleSharedEdit`, keep the person's draft, and retry from the latest `onShared` value. `{merge: true}` merges independent fields of an object value; create an absent field with the precondition `{exists: false}`.
+- **Limits:** HTML 64 KiB, CSS 32 KiB, JavaScript 64 KiB; 30 runs and 60 image previews per minute.

package/docs/reference/workspace-sync.md

@@ -0,0 +1,25 @@
+# Workspace sync
+
+# Workspace sync
+
+The host owns project navigation and synchronization. A Block renders its task controls and output; it does not add a “Continue to the next Block” control. The project rail is the single navigation surface.
+
+`@stillmade/block-sdk/workspace-sync` defines the versioned contract. Saved changes propagate automatically through the shared project document, and every dependent Block reads the newest connected values. Propagation never asks for confirmation. Blocks still require the normal runtime approval when a new paid or hosted execution is necessary.
+
+The shared scopes cover editor media and timing, Canvas, boards, image panels, blueprint, script, shots, voiceover, animation, and chat messages. Presence may include the active selection, normalized cursor coordinates, current editing field, an in-progress chat draft, and the client source (`web`, `desktop`, or `mcp`). Cursor display remains a viewer preference.
+
+```js
+import {
+  WORKSPACE_SYNC_CONTRACT,
+  WORKSPACE_SYNC_SCOPES,
+  workspaceChangeEvent,
+} from '@stillmade/block-sdk/workspace-sync';
+
+const change = workspaceChangeEvent({
+  scope: 'panels',
+  revision: 12,
+  paths: ['strip.panel-4.image'],
+});
+```
+
+The event records which source paths changed. The host owns delivery, revision ordering, conflict handling, and downstream invalidation; Block code must not maintain a parallel navigation or synchronization channel.

package/docs/sdk.md

@@ -0,0 +1,34 @@
+# Download the StillMade SDK
+
+## SDK 0.1.0
+Install it from npm into any folder or project (Node.js 22 or later; its dependencies ship inside the package):
+```sh
+npm install --save-dev stillmade-sdk
+npx stillmade-block create --list
+```
+Run every CLI command as `npx stillmade-block <command>`. Coding agents should read `node_modules/stillmade-sdk/AGENTS.md` before writing a Block. The npm version can be newer than SDK 0.1.0: patch releases repackage the same SDK, and Blocks still declare `sdkVersion` 0.1.0.
+
+Without npm, [download the complete SDK](https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.zip) and run the CLI from the extracted folder as `node packages/block-cli/cli.js <command>`. The same package is also served at `https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.tgz` for installs that cannot reach the npm registry.
+Includes the validators, recipe interpreter, isolated JavaScript runtime and WASM, pinned runtime dependencies and licenses, CLI, TypeScript declarations, examples, and documentation. Requires Node.js 22 or later for local use. No npm installation is required after extraction.
+
+Every finished Block must pass **Remix readiness**. Include editable source, typed I/O, controls, tests and complete license evidence. Remix works automatically through the same package contract; no custom callback or app wiring is needed. CLI validation, builder completion and import enforce it. See [the required remix contract](tools/block-remix.md).
+
+## Documentation only
+[Download offline documentation](https://stillmade.shop/block-sdk/stillmade-documentation-0.1.0.zip).
+Includes Markdown guides, API reference, the paste-ready LLM guide, and the generated API index. It does not contain an execution runtime.
+
+## Individual resources
+- [Complete SDK manual](https://stillmade.shop/block-sdk/SDK.md)
+- [Machine-readable API index](https://stillmade.shop/block-sdk/api-index.json)
+- [Paste-ready LLM guide](https://stillmade.shop/block-sdk/PASTE_TO_LLM.md)
+- [Working examples](examples.md)
+
+## Start using the SDK
+```sh
+node packages/block-cli/cli.js create ./my-block javascript
+node packages/block-cli/cli.js test ./my-block
+node packages/block-cli/cli.js pack ./my-block
+```
+
+## Version policy
+This documentation describes the current SDK 0.1.0. The manifest may declare this exact version or a supported stable range that includes it. See the [compatibility contract](reference/manifest.md#sdk-compatibility). Package release versions and working checkpoints are separate from the SDK version. See [changelog](changelog.md) and [versioning](distribute/versioning.md).