stillmade-sdk 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,103 @@
+# Building StillMade Blocks in this folder
+
+This folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. Scaffold with `node packages/block-cli/cli.js create my-block javascript`, then iterate with `validate my-block` and `test my-block`, check admission with `pack my-block /tmp/my-block.stillmade-block --original`, and finish with `ready my-block`, the same readiness check StillMade runs before a release. `SDK.md` is the complete reference and `PASTE_TO_LLM.md` the detailed authoring guide.
+
+Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+
+## Source of truth
+
+Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
+
+## Define the capability first
+
+Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.
+
+## Blocks compose
+
+A Block is not a mini-app. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
+
+## Use platform primitives
+
+Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.
+
+## No hidden workarounds
+
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
+
+## Interface
+
+If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction genuinely needs one. Expose the capability, not the implementation: meaningful controls, sensible defaults, preview, direct manipulation, progress, clear errors and visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. Follow the host appearance (Light, Dark and White) and the mobile layout contract: one interface for every screen size that fits a 320 CSS-pixel phone without horizontal scrolling.
+
+## Shared editing
+
+Projects are multiplayer. A custom view subscribes through `StillMade.onShared(callback)` and publishes every editable field: give static controls a unique `id` and `data-stillmade-share="field"` (the host owns their synchronization), use `StillMade.bindShared(field, elementId)` for controls created dynamically, and `StillMade.updateShared(values, before, options)` for structured values; private variables and DOM values are not shared. Mark a truly device-only control (playback, hover, device selection) with `data-stillmade-local`. Observe shared outputs as well as state, honor `canEdit` in every mutating callback (read-only participants cannot write), never run, click or call a paid integration in response to a remote update, and preserve conflicting drafts. Shared background work uses `sharedWork` with the `work.shared` permission.
+
+## External services
+
+Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs) and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as typed outcomes the Block reports, not crashes. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
+
+## Dependencies
+
+A Block must declare everything it requires and must not assume anything is installed. Portable packages carry no package dependencies (`portable.dependencies` is empty): inline small, license-compatible code and record its license and notice in `manifest.license` and `manifest.provenance`. Desktop-only tools are reached solely through declared desktop permissions and the host desktop bridge. If a dependency cannot be delivered through the Block runtime, report the incompatibility instead of assuming the user's machine has it.
+
+## Security
+
+Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
+
+## Execution lifecycle
+
+A successful run means more than a returned value. Validate inputs before work; return only declared output ports with values matching their types; run long work as a cooperative job (`job.pending` with monotonic progress) instead of blocking; honor cancellation and the host timeout; keep persistent state in `manifest.state` (module Blocks: `stillmade.storage`) with migration routes so a reopened project and a repeated run behave the same; never leave orphaned jobs, temporary values or corrupted project state after cancellation or failure.
+
+## Useful failures
+
+Errors must say what failed, why it likely failed, whether a retry makes sense and what the user can do, so the native project chat and controller can troubleshoot. In JavaScript, throw an `Error` with that message: the host reports it as a `JAVASCRIPT` run failure carrying your message (guest code cannot set its own error code). Reject invalid or oversized input up front with a message naming the input and the limit. Never reduce a failure to "Something went wrong".
+
+## Adapt to the platform
+
+Do not modify StillMade core because a request does not fit immediately. First implement the capability entirely through documented SDK and platform primitives. If that is impossible, classify why: A Block implementation problem (fix it), B missing SDK exposure of an existing host capability, C missing generic platform primitive, D security or permission restriction, E runtime or language incompatibility, F fundamentally incompatible capability. For B or C, name the smallest general primitive that would serve this Block and a meaningful class of future Blocks (shaped like `files.watch()` or `media.transform()`, never `supportThisSpecificBlock()`). Return `{"unsupported":"exact reason","gapClass":"B|C|D|E|F","primitive":"..."}` instead of a package that pretends to work.
+
+## What StillMade verifies
+
+StillMade runs the readiness check on every Block it admits: manifest and contract validation, the source security scan, every fixture in the sandbox, wrong-type and over-limit inputs, declared output types, cancellation and timeout cleanup, state reopen and repeated runs, composition with a real upstream and downstream catalog Block through the resolver, a Project Type preview, the shared-interface contract with two participants editing a custom view in the real preview runtime (their edits must converge and a read-only participant must not write), and phone and desktop layout. Design for all of them and include normal and edge-case fixtures (1 to 50; stateful Blocks also declare `expectedState`). Test materially different inputs within the declared capability, and document limitations instead of overclaiming generality. Two of these checks need StillMade itself: two-participant shared editing and the phone and desktop UI profile run in StillMade's preview runtime when the Block is imported or released, so `ready` in the downloaded SDK reports them as not verified rather than passed.
+
+## Project Types
+
+A Project Type is an ordered production workflow. Each Step's primary output must be a compatible input for the next Step, secondary values come from permitted project context, and every member Block obeys this contract. Install Blocks into a realistic Project Type: project chat must understand each Step, inputs must resolve intuitively, outputs and execution state must be visible, failures must be diagnosable, and the user must be able to continue through the workflow.
+
+## Readiness report
+
+Finish with a Block Readiness Report: capability, contract (inputs, outputs, permissions, dependencies), platform APIs used, tests actually performed and their results, the composition test (upstream, Block, downstream), known limitations, unsupported requirements and any platform gap with its smallest general primitive. Choose exactly one status: PRODUCTION READY (every applicable check passed), READY WITH DOCUMENTED LIMITATIONS (works reliably within stated boundaries), BLOCKED BY PLATFORM CAPABILITY (needs a missing generic primitive) or FAILED. Never label a Block production ready to satisfy a request, and never claim a check ran when it did not.
+
+## Definition of done
+
+A Block is done only when every applicable item holds. Passing a compile, one unit test, a rendered UI or one happy-path sample is not done.
+
+- DOD-01 Installs through the normal Block mechanism
+- DOD-02 Manifest and contracts validate
+- DOD-03 Runs through the normal runtime
+- DOD-04 Required permissions are declared
+- DOD-05 Required dependencies are reproducible
+- DOD-06 Real inputs work
+- DOD-07 Invalid inputs fail correctly
+- DOD-08 Outputs conform to their declared types
+- DOD-09 Outputs are usable by compatible downstream Blocks
+- DOD-10 Universal resolver integration works
+- DOD-11 Applicable project context works
+- DOD-12 Applicable persistence works
+- DOD-13 Applicable multiplayer behavior works
+- DOD-14 Cancellation and failure cleanup work
+- DOD-15 UI works in relevant states and screen sizes
+- DOD-16 No hidden developer setup is required
+- DOD-17 Security boundaries remain intact
+- DOD-18 Relevant integration tests pass
+- DOD-19 Works after application restart or project reopen
+- DOD-20 A realistic Project Type execution succeeds when applicable
+
+## Platform gap classes
+
+- A: Block implementation problem
+- B: Missing SDK exposure of an existing host capability
+- C: Missing generic platform primitive
+- D: Security or permission restriction
+- E: Runtime or language incompatibility
+- F: Fundamentally incompatible capability

package/AGENT_CONTROL.md

@@ -0,0 +1,293 @@
+# JSON assistant access
+
+StillMade assistants use host-owned JSON tools rather than pixels or DOM selectors.
+Every Block using the shared playground automatically exposes its manifest inputs
+and outputs to an explicitly connected tab. New Blocks need no special MCP tool
+name or duplicated UI implementation. Use meaningful port names and declared types,
+requirements, defaults, context sources and UI choices.
+
+New import admission now reports two separate hard constraints before a Block can
+become usable. **API and integration availability** rejects executable ambient
+network/key access and retained source dependencies that are not mapped to one
+exact supported host capability. A supported capability remains review-required:
+the host must still prove the current account connection, settings, quote, run
+budget and output. Retained JavaScript, TypeScript, Python, Ruby, Go, Rust, Java,
+Kotlin, Swift, PHP, shell and endpoint configuration are inspected for common
+network clients, credential names and known provider endpoints; unknown clients
+remain unavailable rather than being treated as local code. **Chat and MCP JSON
+control** verifies that every ordinary
+input—including an optional one—has a safe JSON or permission-checked media
+transport, that inputs and outputs explain their purpose, and that generic
+`json`/`object` values and their arrays declare a bounded field schema. Generic
+structured outputs also require a schema before the resolver may match them. An optional approval, file
+bundle, or other UI-only value cannot bypass this gate merely because the Block
+has a default path. These checks apply to new creation/import admission, not
+retroactively to immutable installed releases.
+
+Admission also reports the **Input/output resolver contract** separately. Every
+input must declare its physical type, exact semantic meaning, required/optional
+status and description; every output must declare its type, meaning and
+description. This is resolver metadata, not evidence that any arbitrary ports can
+connect: workflow composition still validates the exact meanings, schemas,
+versioned adapter pin and adapter permissions for each proposed edge.
+
+Code is therefore not the control manual. The pinned manifest is: Block and port
+descriptions explain intent, types and schemas define accepted JSON, UI choices
+provide enums, permissions identify host-owned context/media, and fixtures prove
+the same runtime contract. Both native chat and MCP consume this one contract, so
+authors do not teach each model a separate sequence or duplicate their visual UI.
+The admission result materializes that contract as a compact
+`block-agent-json/1` manual: Block identity/runtime, every input's type, semantic,
+required/default status, description, transport, limits and bounded choices,
+described outputs, and the host action IDs for inspection, JSON edits, media
+selection, execution review and receipts. Models consume this declared playbook;
+they do not infer a workflow from package code or memorize a custom UI. Schema
+and choice material has a shared aggregate budget in both admission manuals and
+live pages; `schemaPartial`, `optionsPartial`, counts and page metadata make every
+omission explicit so large contracts cannot break the heartbeat or masquerade as
+complete context.
+
+`inspectAgentBlock(content, values, {offset, limit, locked})` returns bounded
+metadata: Block ID/version, purpose, declared output ports, input presence and
+locks, missing required inputs, supported devices, permission scopes, and the
+state and execution contract. Live adapters also expose their current actions
+and output presence through `inspectAgentPorts`. Text contents, URLs, bytes and credentials are omitted.
+`false` and `0` are present. Empty strings/lists and missing/invalid values are
+different. Media presence never establishes access, successful loading or payment.
+The host's input validator and sandbox admission remain authoritative.
+
+The shared preview adapter supports reviewed `set_input` for text, number, integer
+boolean, primitive-list and JSON ports. Context and upstream values stay locked. Edits use the same
+change handler and invalidate the old result. They are preview changes, not proof
+of a saved production project. Media selection uses offered opaque choices and the host media broker, including
+ordered lists of up to 16 items. Local recipe/JavaScript previews expose a reviewed
+run action with cancellation and real skipped/failure outcomes. Install, publish
+and paid execution are not generic input actions and must not be faked through
+JavaScript or a network request.
+
+## Additional workspace actions
+
+Native workspaces must own typed adapters for their own behavior. Trusted host
+registration supplies `inspect()` with a revision and explicit actions containing
+`id`, `label`, JSON `parameters`, `effect`, `parse(args)` and `run(args)`. The
+registry is first-party integration code and is never passed to sandboxed packages.
+Package text cannot register callbacks, choose a lower approval tier, or bypass
+host permissions. Existing app function names are not an external action API.
+
+Actions may additionally declare `locate(args)`, returning the currently mounted
+DOM element that visually owns that exact action. The host uses it only to place
+the labeled MCP activity cursor when application begins; review starts on the
+host approval card. It grants no DOM automation, is never serialized to MCP, and
+must return `null` when the exact target is unavailable. Without it the host
+points at the registered workspace or review card rather than inventing a
+selector.
+
+An adapter must expose copied metadata only, invalidate its revision when relevant
+source/inputs/permissions change, reject stale targets again immediately before
+execution, use existing storage acknowledgement, and retain sandbox, paid-budget,
+permission and cancellation behavior. Return what actually happened: navigation
+requested, preview updated, or saved with a durable revision. Unavailable actions
+stay unavailable. Never advertise a whole workspace as supported because its
+metadata can be inspected.
+
+MCP clients use `get_agent_guide`, discover `list_app_sessions`, inspect the
+selected tab, then request one supported action with its exact revision and a
+stable request UUID. The user reviews it in the app. Read `get_app_action` before
+continuing. An uncertain dispatch cannot be retried with a fresh ID.
+
+SDK source exports are updated. Prebuilt ZIPs and generated SDK downloads must be
+regenerated through the existing packaging process when a build is authorized.
+
+## Source API
+
+Import `inspectAgentBlock`, `inspectAgentPorts`, `inspectAgentDocument`,
+`agentInputChoices` and `parseAgentInput` from the SDK entry point.
+`inspectAgentDocument(state, {limit:40, maxDepth:3})` supplies bounded nested
+presence paths; omitted children are explicit, and text/media contents stay out.
+`agentInputChoices(manifest, locked)` describes supported editable ports and UI
+choices. `parseAgentInput(manifest, {field, value}, {locked, busy, disabled})` checks
+types, numeric limits, choices and size before returning a copied value. This
+helper does not grant permission, save a change, or authorize execution.
+
+Trusted native modules can use `defineNativeAgentAdapter` and
+`bindNativeAgentActions` with exact Block pins. Mounted React modules can use
+`useNativeAgentControls` from `native-agent-react.jsx`; this separate React entry
+requires the trusted host provider and is not a sandbox API. `available` must be a
+function, and handlers must preserve host checks and report real outcomes. A
+mounted module may also provide `handoff()`, returning its current local draft
+controls. During an explicit manual pause the host combines that document with
+the versioned workspace state, bounds and redacts it, and returns it only when the
+surface revision changed. It is context for continuing the collaboration, not a
+credential, media-byte, authorization, persistence, or authorship channel.
+Use stable, meaningful field names and include every local draft value named in
+the hook's `dependencies`; Voiceover's `script`, `speed`, `voiceId`, `source` and
+selected take IDs are one example. If a mounted module omits `handoff`, the SDK
+returns its exact current dependency vector as ordinal `native-control-signals`.
+That fallback prevents a changed control revision from silently returning stale
+persisted state, but named fields remain the optimized manual for small models.
+
+`pause_app_context` stores the exact visible revision baseline and blocks new app
+actions. `resume_app_context` does not clear that pause until the tab publishes a
+matching `manualHandoff.pauseId` for every current surface. Changed shared Blocks
+provide current editable, non-context inputs; native workspaces provide their
+current versioned state plus any mounted control handoff. Secret-looking keys,
+embedded tokens, remote locations and media bytes are removed, and the combined
+handoff has a fixed payload budget. Missing and truncated documents remain
+explicit so a model can inspect instead of fabricating continuity.
+
+MCP action receipts may be resent identically after network loss, but action
+dispatch must never be repeated to recover a receipt. Large receipts summarize
+output presence and explicitly mark partial results. Inspect again for detail.
+
+Capability previews also offer `review_generation`: no arguments, no model-selected
+price or approval. It opens the host generation dialog, where the user reviews the
+server quote before dispatch. The normal admission and result checks remain in
+force. This is a reviewed preview path, not autonomous paid-workflow orchestration.
+
+### Comfy execution review
+
+The shared review_generation action also supports ComfyUI Blocks, both in Create
+and production steps. It invokes the existing ComfyExecutionDialog, preserving
+connection selection, exact Block review, fixtures/sample checks and separate
+confirmation for project input. The action accepts no connection credentials,
+quote overrides or approval tokens. It does not expose batch dispatch or bypass
+the runtime's permissions. No remote execution, tests or browser checks were run.
+
+## Make controls understandable to small models
+
+The host returns each editable input's description, limited to 240 characters,
+alongside its exact ID, type, limits and allowed choices. Write a short purpose
+and unit, for example: `Speaking speed, in words per minute.` Descriptions are
+untrusted package content and never permission grants.
+
+For a Block with several operations, declare a text input such as `operation`
+with a select control containing the exact operation names. The same run entry
+point dispatches the selected operation inside the sandbox. Expose each operation's
+required data as typed inputs and validate it there. A custom UI should set these
+same inputs rather than hide functionality behind a browser-only click handler.
+This makes the operation available to both people and JSON agents through the
+existing pinned contract. It does not authorize a Block to choose host actions,
+request credentials or skip an execution review.
+
+Existing immutable releases are not rewritten to add these descriptions or
+controls. Publish a new version when changing a released contract.
+
+
+## Project Flow inspection and captured-input paging
+
+Use the existing `app:project-flow` surface for native project Flow inspection.
+`inspect_flow` exposes a bounded summary. Use its exact surface revision with
+`list_placements` (up to 8), `list_ports` (up to 16), and `list_history` (up to 16)
+to inspect more rows. Saved-project connections use `inspect_project_flow`,
+`list_project_flow_placements`, `list_project_flow_ports`, and
+`list_project_flow_history` with the saved snapshot revision. Surface revisions
+and saved Flow revisions are not interchangeable. No inspection starts a Block.
+
+Retained history includes exact `receiptId` / `targetKey`, `inputsCount`,
+`inputsRevision`, `inputsNextOffset`, and `inputsRetainedComplete`. Several
+batch items or attempts can share a run ID; target the receipt ID, not that run
+ID alone. Native `list_run_inputs` and external `list_project_flow_run_inputs`
+read the same captured-input projection, with arguments:
+
+```json
+{"placementId":"receiving-step","receiptId":"<16-hex receipt ID>","revision":"<16-hex inputsRevision>","offset":16,"limit":16}
+```
+
+The external tool additionally requires `projectId`. This revision identifies
+the captured-input evidence, not the surface/Flow snapshot. Each page contains
+at most 16 named input identities and the next offset. Current project access,
+the exact retained receipt and its evidence revision must still agree. Reject
+stale pages and inspect again; do not substitute current source choices.
+`retainedComplete:false` remains incomplete at the final retained page. Missing
+older records, lost preview inputs and omitted nested collection identities
+cannot be inferred from the page. No raw input values, automatic recovery,
+generation, spending or project changes are authorized by these reads.
+
+### Saved shared tasks
+
+Use `inspect_project_tasks` with the current project read grant to inspect an exact task or bounded task pages without navigation. `control_project_task` requires a separately selected project-control grant plus read access, the exact requester/task/instruction/control revisions and a requestId. Only pause, takeover, cancel and resume are supported. Resume queues revalidation, never a spending or action approval. Identical request replay returns the original receipt and current task without repeating effects. Native task buttons retain the same coordinator rules and their existing UI; do not invent a native surface action from the external tool name.
+
+### Retained result inspection
+
+Retained unselected results have a separate read-only inventory. The Result tab
+shows eight candidates at a time. Use native `list_retained_results` or external
+`list_project_flow_retained_results` with `{placementId, revision:
+unusedResultsRevision, offset, limit}` (plus `projectId` externally); list pages
+contain at most eight candidates. Only records still retained for the current
+Block package are included: unused single results, unselected connected results,
+and batch records explicitly marked unused after a source change. The ordinary
+batch picker is separate. `historyComplete:false` means evicted history is not
+recoverable through this inventory, even at its final page.
+
+Each candidate has an exact `candidateId`, `outputDigest`, run/item/attempt
+metadata, and captured-input/output counts and cursors. Native
+`inspect_retained_result` and external `inspect_project_flow_retained_result`
+accept `{placementId, revision: unusedResultsRevision, candidateId, section,
+offset, limit}`. Sections `inputs` and `outputs` page at most 16 identities or
+previews. Sections `text` and `collection` also require `outputKey` and the exact
+preview `path`; text requires its returned `identity` and permits at most 4,000
+characters, collections at most 16 members. Reuse the exact candidate and list
+revision on every page. Changes anywhere in retained records, package or preview
+restrictions invalidate that revision. Inspect fresh state after a conflict.
+Current project read access is rechecked after saved reads; native/UI caches
+reset when the authorized reader changes. External/native results redact media
+addresses. Sensitivity and prior preview restrictions still apply; a restricted
+candidate cannot become inspectable through a later page. Captured inputs remain
+bounded metadata and may be incomplete; nested structured previews disclose
+omitted fields rather than claiming a complete document. These reads never
+select a candidate, restore media, dispatch work, or substitute current output
+for a retained value.
+
+## Ordered targets for controls that run several Blocks
+
+A host control that executes multiple placements exposes `executionTargets` on
+its native inspection snapshot, keyed by the offered action ID. Each value is
+`{contractVersion:1, partial:false, steps:[{placementId,blockId,version}]}`.
+Steps list the runner's actual ordered targets and exact saved releases. Do not
+infer this list from labels, output types or a general “ready” flag. A missing,
+truncated or unresolved target list uses `partial:true`; fallback branches whose
+exact runtime target is unresolved cannot be advertised as complete.
+
+The controller checks every target's current contribution/version in the retained
+workflow plan, checks dependency order, and requires ready materialized outputs
+for incoming producers outside that run. A producer inside the same run may
+materialize its output before the consumer runs; the normal executor still
+validates the actual handoff. Inspection metadata is not execution authority.
+Task fences, live revisions, source validation, sandbox admission, reviews,
+aggregate budgets and output receipts remain with their existing host controls.
+This batch target contract does not itself prove scalar setting agreement,
+artifact quality, fallback execution or final goal completion.
+
+For whole-goal batch proposals, the backend also compares planned non-context
+scalar inputs against the current saved `blockInputs` or declared defaults.
+Expected values must be valid scalar task hypotheses tied to the current owner
+instructions and exact Block release. A matching UI snapshot is insufficient;
+the authenticated task-fenced readback is checked before a proposal is returned,
+including after controller recovery changes the proposed action. This readback
+stores no plan, applies no edit, approves no expense and starts no Block.
+Connected input ports remain under exact source/handoff admission. Media and
+structured-input goal expectations require their separate typed contracts and
+inspection; scalar agreement does not establish them or result quality.
+
+## Typed goal-input hypotheses
+
+`agent-data-plan/1` complements scalar input plans with exact non-secret media
+and document expectations. Rows bind placement, Block ID/version, field, owner
+goal quote, reason and a SHA-256 `valueDigest`. A changed expectation needs its
+exact `previousDigest` and a `revisionReason`; identical revision replays are
+idempotent. The task retains these hypotheses only while the instruction fence
+and canonical Block source remain current.
+
+The generic native `read_input_identity` control reads the current field through
+its declared contract. Media digests include ordered kind/asset/version identities
+and exclude refreshed URLs and labels. Structured values and pixel images bind
+the entire validated value. Context, secrets and approval inputs are excluded.
+Pending supported typed setters and media selections acquire hypotheses before
+review; they do not become evidence of applied inputs.
+
+Before proposing a whole-goal batch or sequential Block run, the backend compares retained/proposed
+hypotheses with actual saved unconnected inputs and rejects unavailable or changed
+values. Connected inputs continue through the saved graph and runtime handoff
+checks. This guard covers whole-goal batch and sequential Block proposals, not every
+explicitly scoped single-Block task. Identity agreement proves neither semantic goal alignment,
+media rights, execution approval, spending authority nor output quality.

package/BROWSER_APPLICATIONS.md

@@ -0,0 +1,140 @@
+# Browser application bundles — experimental source contract
+
+This is an additive source and execution-evidence contract under development.
+The exact reviewed Method Draw package has a private desktop install, editing
+and SVG export path. This does not admit arbitrary browser applications or
+make this runtime available through portable archives. Other repositories
+still require their own review and working acceptance evidence.
+
+The intended profile preserves a real built application's HTML, JavaScript,
+CSS, fonts, images and optional single-thread WebAssembly, plus a small
+Block-owned adapter. Original styling is the default. It does not rebuild the
+application UI using StillMade controls. The shared host supplies navigation,
+identity, storage authority, permissions and execution; application-specific
+behavior remains in the bundle and its independently versioned adapter.
+
+## Bundle identity and resources
+
+`defineBrowserApplication` validates a detached `desktop-browser-application/1`
+bundle. Every asset has a canonical relative path, MIME type, decoded byte count,
+SHA-256 and canonical base64 payload. Entry HTML and adapter JavaScript must be
+present. The contract rejects URL paths, path traversal, file/directory collisions,
+case collisions, unsupported file metadata, invalid encoding and changed bytes.
+`encodeBrowserApplicationFiles` accepts already-read regular-file bytes;
+filesystem importers remain responsible for rejecting links and escaping paths.
+
+Limits are explicit and independent of the older portable archive format. A
+bundle can contain at most 2,048 assets, 64 MiB per asset and 128 MiB total decoded
+bytes. Input, state and output messages remain bounded separately. Successful
+validation proves byte integrity and schema conformance, not code safety, license
+permission, dependency closure, build success or application behavior.
+
+The first profile declares no ambient networking, workers, native services or
+paid integration access. Single-thread WASM is an explicit requirement, not an
+automatic permission. Arbitrary development servers, native Node modules,
+service workers, threaded WASM and full-stack backends need distinct profiles
+and verified host capabilities. Existing SDK restrictions are not removed.
+
+Inspect compiled dependencies as well as asset extensions. For example, a
+checked-in editor bundle may contain base64 WebAssembly or dynamically create
+workers without shipping any `.wasm` file. The current asset/declaration check
+does not prove those paths are absent. Admission must record which paths are
+needed, and the selected runtime must enforce its CSP, target and resource
+policy when code executes. A dead or explicitly unavailable feature is different
+from a verified fallback. The current development Linux worker rejects declared
+WASM and blocks worker creation; it does not establish general WASM support.
+
+## Adapter lifecycle and completion
+
+An adapter needs to receive meaningful typed inputs, restore host-scoped editable
+state, checkpoint changes, export the actual result, cancel and dispose. Use
+original application APIs and controls. Keep autosave separate from explicit
+completion; mounting a UI or retaining the original input is not evidence of
+the requested transformation.
+
+`prepareBrowserApplicationMount` binds a mount request to the exact package,
+bundle, input and state revision. A mount acknowledgement carries no outputs and
+cannot pass execution validation.
+
+`prepareBrowserApplicationExecution` additionally binds the named declared
+operation. Interactive applications require an explicitly interactive host;
+headless execution needs an implemented operation. The trusted host must issue
+the completion receipt only after the actual operation, output checks and
+current permission/state checks. `validateBrowserApplicationExecutionResult`
+and the saved-record validator check those bindings; their result explicitly
+keeps `independentlyVerified:false`. Arbitrary callers can fabricate JSON, so
+these pure helpers do not authenticate evidence or authorize adoption.
+
+`runBrowserApplication` requires an explicitly supplied trusted executor. It
+never falls back to evaluating source in the host or treating a mounted page as
+success. Cancellation and timeout signal the executor; actual process/resource
+termination is the executor's responsibility and needs independent verification.
+
+## Guest registration
+
+`installBrowserApplicationGuest({target,operations,messageBytes})` is the
+framework-neutral lifecycle dispatcher for a trusted bootstrap. It installs only
+`target.stillmadeApplication.register(adapter)` and returns a separate controller
+to that bootstrap. It does not install a runtime or grant host access.
+
+The Block-owned adapter registers exactly these four methods once:
+
+| Method | Adapter result |
+| --- | --- |
+| `mount({inputs,state,signal})` | Restore the original UI and return exactly `{mounted:true}`. |
+| `serialize({signal})` | Return the versioned editable document as plain JSON. This is a snapshot, not output completion. |
+| `execute({operation,inputs,stateRevision,signal})` | Run a declared operation and return its raw typed output map; the dispatcher adds the `{outputs}` envelope. |
+| `dispose()` | Release adapter-owned resources. Return values are discarded. |
+
+Use closures or explicitly bound functions when application methods depend on
+their original receiver. The controller enforces mounting before serialization
+or execution, one active call, exact mounted inputs, declared operation names,
+bounded plain JSON, and rejection of guest receipt fields. Cancellation discards
+late results and leaves the guest usable only for disposal. Disposal itself is
+cooperative; a hung application must be terminated by the trusted host.
+
+The dispatcher is self-contained for inclusion in a reviewed bootstrap. Its
+JavaScript object checks are correctness checks inside an untrusted realm, not
+security boundaries. The host must revalidate every message, own checkpoint
+identity and UI-event sequencing, issue receipts, check current permissions,
+persist revisions and enforce resource limits outside the guest. No account
+token, filesystem access, native proxy or generic network function is exposed.
+
+## Runtime gates still required
+
+- Serve only exact verified bundle assets. Keep application sessions isolated
+  from host origin, cookies, local files, native IPC, credentials and one another.
+- Enforce navigation, external request and device denial. A sandboxed iframe,
+  request interceptor or CSP alone does not establish complete egress denial.
+- Keep the host responsive under infinite JavaScript/WASM loops and memory
+  pressure. Resource and cancellation enforcement must live outside the guest.
+- Scope persistence to account/project/placement and exact source. Shared state
+  needs permission checks, revision conflicts, recovery and flush-on-completion;
+  origin-global `localStorage` cannot establish that contract.
+- Build in a disposable secret-free worker with pinned dependencies, bounded
+  resources and no unrestricted network during source execution. Preserve
+  licenses, binary assets and exact output identities.
+- Run original UI operations and compare upstream/adapted exports. Then prove
+  a real producer → application → consumer chain, save/reopen, two placements,
+  cancellation, revocation, stale-result rejection and adversarial isolation.
+
+Method Draw is being used to study the first complete static editor route.
+Its remote fonts, global localStorage and SVG import behavior require explicit
+adaptation; an original-page baseline is not a completed Block integration.
+
+## Reproduce the reviewed package outside the repository
+
+The downloadable SDK zip includes `packages/block-sdk/browser-application.js`
+and `browser-application-execution.js`. The Method Draw source folder contains
+its own pinned upstream bytes, adapter, source hashes and package builder. With
+Node.js 22 or later, extract the SDK zip, place the complete Method Draw folder
+at `blocks/repository/methoddraw` inside the extracted directory, and run:
+
+```sh
+node --input-type=module -e 'import {buildMethodDrawPackage} from "./blocks/repository/methoddraw/build-package.mjs"; import {digest} from "./packages/block-sdk/contracts.js"; const source=await buildMethodDrawPackage(); console.log(await digest(source));'
+```
+
+For the reviewed source and SDK 0.1.0 archive the digest is
+`084ed75a82a66011344bcb609a12de018ccb4e20b828fabc2afef60399c5f6eb`.
+This reproduces source packaging only. It does not execute the editor, grant
+private installation, or show that a different GitHub repository is eligible.

package/BROWSER_APPLICATION_ARTIFACT_REFERENCES.md

@@ -0,0 +1,85 @@
+# Browser application artifact references
+
+`packages/block-sdk/browser-application-artifacts.js` defines immutable source and draft references, with verification when a trusted host loads their bytes. These are additive contracts. They do not install the browser application runtime, implement storage or grant access. Generic package admission and execution remain unavailable for `browser-application`.
+
+An experimental host can represent source with the small descriptor below. Existing saved-project validation must be explicitly extended before it accepts this form. The full application remains an immutable, separately stored artifact; hydrated source is ephemeral and should not be copied back into the saved project or collaboration operations.
+
+```js
+const {descriptor, bytes} = await createBrowserApplicationSourceArtifact(source, {
+  entityId: exactSourceEntityId,
+});
+// descriptor = {
+//   manifest,
+//   sourceRef: {
+//     schemaVersion: 1, storage: 'block-source-v1', entityId,
+//     version, digest, byteLength,
+//   },
+// }
+```
+
+`bytes` is a `Uint8Array` containing `stableStringify(source)` encoded as UTF-8. Its SHA-256 equals the existing SDK `digest(source)`; `sourceRef.digest` always identifies the full source, including the application assets and optional fixtures. The version must equal the manifest version. No URL, bucket key, alternate storage type or floating `latest` reference is accepted. Store exactly these bytes, without reformatting JSON. Creation fully validates the application bundle and every asset. `defineBrowserApplicationSourceDescriptor` validates and freezes a detached descriptor without downloading source.
+
+```js
+const source = await hydrateBrowserApplicationSource(descriptor, {
+  authorize, fetchBytes, signal, timeoutMs: 30_000,
+});
+```
+
+The host supplies both callbacks; neither callback is available to guest application code:
+
+```ts
+authorize(binding, {signal, phase}) => true | false | Promise<boolean>
+fetchBytes(reference, {signal, maxBytes})
+  => Uint8Array | AsyncIterable<Uint8Array> | Promise<either>
+```
+
+`authorize` runs before fetching and after all validation. Only literal `true` grants access. For source, its binding is `{kind: 'source', descriptor}`. The trusted host must check the current actor, accessible entity, exact published or retained version, digest, licensing, team scope and revocation, as applicable. It must resolve storage keys itself from this authorized identity. Every hydration repeats these checks; there is no cache. A returned source grants no continuing permission to execute later: execution must check access again at its own acceptance boundary.
+
+The helper verifies the declared byte count, strict UTF-8, canonical JSON, full-source SHA-256, exact manifest equality, full browser application contract and every bundled asset. It rejects malformed JSON, duplicate/prototype keys, BOMs, extra descriptor fields and corruption. Returned descriptors and hydrated values are detached and deeply frozen. The original inline source is unchanged.
+
+## Project application draft state
+
+The host assigns the artifact identity and revision. Scope comes from an authenticated project placement, never from guest claims.
+
+```js
+const {draft, bytes} = await createBrowserApplicationStateArtifact(state, {
+  scope: {projectId, placementId},
+  packageDigest, revision, id,
+});
+// draft = {
+//   schemaVersion: 1, packageDigest, revision,
+//   stateRef: {
+//     storage: 'project-application-state-v1', id, sha256,
+//     byteLength, mime: 'application/json',
+//   },
+// }
+```
+
+The exact canonical artifact payload is `{schemaVersion: 1, id, scope: {projectId, placementId}, packageDigest, revision, state}`. Its SHA-256 equals the SDK digest of that full payload. State must be a plain JSON object. The opaque identifiers accept 1–128 ASCII letters, digits, dots, underscores and hyphens, starting with a letter or digit; reserved prototype names and `latest` are rejected. Revisions are bounded nonempty strings. `defineBrowserApplicationDraft` validates and freezes the small reference without loading state.
+
+```js
+const state = await hydrateBrowserApplicationState(draft, {
+  scope: {projectId, placementId},
+  authorize, fetchBytes, signal,
+});
+```
+
+State authorization receives `{kind: 'state', scope, draft}` with the same two phases. Hydration verifies byte length/hash and every binding inside the stored payload: project, placement, package digest, revision and artifact identity. It returns only frozen state. A missing, corrupted, stale, revoked or cancelled load does not mutate the saved reference; the caller should preserve the recoverable draft and report the failure.
+
+## Bounds and host responsibilities
+
+| Boundary | Limit |
+| --- | --- |
+| Encoded source artifact | 180 MiB |
+| Source descriptor | 64 KiB |
+| Complete encoded state artifact, including its envelope | 4 MiB |
+| Draft descriptor | 4 KiB |
+| Hydration timeout | 30 seconds default, 120 seconds maximum |
+
+The existing bundle limits still apply: at most 2,048 regular-file assets, 64 MiB per asset and 128 MiB decoded in aggregate. The guest's 4 MiB message cap remains separate. Existing inline package, custom-view, Step-state and collaboration limits are unchanged; a guest state near its message cap may exceed the artifact cap once its envelope is encoded.
+
+Prefer an asynchronous byte stream for large source reads. The helper rejects excess bytes before retaining the excess chunk, limits streams to 65,536 chunks, and attempts to close a failed iterator. A buffered callback must enforce `maxBytes` before allocating/downloading the entire response; checking an already allocated response cannot prevent that allocation. The host must propagate the supplied signal to its underlying I/O. Abort and timeout reject pending callbacks even if those callbacks ignore cancellation, and late results are discarded. Timers and JSON/asset verification are cooperative bounds, not CPU or process isolation.
+
+The host still owns immutable writes, authoritative project/package/placement checks, atomic revision acceptance, permission checks at storage and execution boundaries, quotas, retention, export/backup, deletion and garbage collection. This helper supplies no actor authentication, database transaction, encryption, worker containment, durable state route or execution receipt. It does not make an application production-ready.
+
+Focused tests include the real pinned Method Draw package: its multi-megabyte original source becomes a descriptor below 8 KiB, hydrates byte-equivalently, and remains rejected by ordinary package admission. Other tests cover exact state size boundaries, stream overflow, cancellation, timeout, authorization revocation, wrong identities, manifest/assets corruption and malformed JSON. Run `npx vitest run packages/block-sdk/browser-application-artifacts.test.js` without network or paid services.

package/CLAUDE.md

@@ -0,0 +1 @@
+Read AGENTS.md before building: it is the StillMade Block builder contract for this SDK folder.