stillmade-sdk 0.1.41 → 0.1.43

package/docs/build/interface-design.md

@@ -0,0 +1,343 @@
+# Block interface design
+
+# Block interface design
+
+A Block page should work at a glance: the thing being made is the biggest
+thing on the page, there is one obvious next action, choices are pictures, and
+words appear only when someone needs them. The app owns project navigation;
+a Block owns its production surface. Neither needs a second shell.
+
+Most Blocks need no custom view: generated `manifest.ui` controls already
+follow these rules. Write a custom view only when the core interaction needs
+one, and start it from the Block kit.
+
+## 1. Start from the Block kit
+
+StillMade adds the Block kit stylesheet (`packages/design-system/block-kit.css`)
+to every Block view, standard and frame. Use its classes and ship little or no
+CSS of your own. Every kit rule has zero specificity, so your own CSS always
+wins. Open `packages/design-system/block-kit.html` in a browser to see every
+piece in Light, Dark and White.
+
+```html
+<main class="sm-block">
+  <fieldset class="sm-choices" id="look" data-stillmade-share="look" data-ratio="16:9">
+    <legend>Look</legend>
+    <label><input type="radio" name="look" value="warm" checked><img src="data:..." alt=""><span>Warm</span></label>
+    <label><input type="radio" name="look" value="cool"><img src="data:..." alt=""><span>Cool</span></label>
+  </fieldset>
+
+  <div class="sm-field">
+    <div class="sm-label">
+      <label for="caption">Caption</label>
+      <details class="sm-hint"><summary aria-label="About captions" title="About captions"></summary><p>Shown over the first two seconds.</p></details>
+    </div>
+    <input id="caption" data-stillmade-input="caption" placeholder="Optional">
+  </div>
+
+  <details class="sm-more">
+    <summary>More</summary>
+    <div class="sm-fields"><!-- secondary settings --></div>
+  </details>
+
+  <div class="sm-actions">
+    <button type="button" class="sm-primary" id="run" data-stillmade-action="run">Make the clip</button>
+    <p class="sm-status" id="status" role="status"></p>
+  </div>
+
+  <section class="sm-stage" id="stage" data-ratio="16:9" aria-live="polite">
+    <div class="sm-empty" id="empty">
+      <span class="sm-glyph" data-glyph="video" aria-hidden="true"></span>
+      <p>Your clip</p>
+    </div>
+  </section>
+</main>
+```
+
+With an `sm-stage` as its direct child and no `data-layout`, `sm-block` puts
+the inputs on the left and the stage on the right from 860 px wide. Under that
+everything stacks in the page's order, so the stage comes last in the markup:
+the inputs, the button, then the result's place under it.
+
+| Class | Use it for |
+| --- | --- |
+| `sm-block` | The one workspace. With an `sm-stage` child, the controls sit left and the stage right from 860 px; narrower, they stack in the page's order. `data-layout="stack"` keeps one column; `"split"` is an older layout with the stage on the left. |
+| `sm-stage` | The thing being made: preview, media or result. `data-ratio="16:9"`, `"9:16"` or `"1:1"`. |
+| `sm-empty` | An empty stage: a glyph, at most five words, one action. |
+| `sm-choices` | Picks shown as pictures (`img`, `.sm-swatch`, `.sm-glyph`) and one or two words. `data-compact` for short text chips, `data-segmented` for one connected row of three or four short options. The pick is filled with the kit's ink, so it reads at a glance; a `disabled` fieldset keeps its pick and fades the rest. Chips and segments scroll sideways on a phone. Give the `fieldset` an `id` and `data-stillmade-share` so teammates see the same pick. |
+| `sm-field`, `sm-fields` | One short setting on one row, its label beside the control; a responsive group of them. On a phone the control wraps under its label only when both do not fit. A textarea, picture choices, file tiles or a list keep the label above. |
+| `sm-settings` | Short settings side by side, each label beside its control; a narrow cell wraps the control under its label. |
+| `sm-list` | Many items, one line each: a thumbnail, one line of text, a short fact. An item that opens in place is an `li` holding a `details`. `data-peek` shows three on a phone, with a last `li.sm-list-more` button that sets `data-open`. |
+| `sm-clamp` | Long text that shows five lines on a phone until it gets `data-open`. |
+| `sm-actions` | One `sm-primary`, then `sm-quiet` buttons and `sm-icon` buttons (each with `aria-label` and `title`). |
+| `sm-status` | Live state beside the action: `data-state="loading"`, `"success"`, `"waiting"` or `"error"`. |
+| `sm-more` | A closed `<details>` for secondary settings. |
+| `sm-hint` | A closed `<details>` (i) for an explanation that might help. Its words show on hover or focus, or a tap on touch screens. |
+| `sm-gallery` | A grid of results or media. `data-size="small"` for input files: more tiles per row as the screen widens. |
+| `sm-media-off` | A picture or clip that cannot show here (on another device, or it did not open): a quiet tile in its own shape (`--sm-photo-ratio`, the tile's shape in a gallery) holding the `image-off` glyph, the reason in `aria-label` and `title`, no words inside. |
+| `sm-add` | The + tile that adds files to an input: `<button type="button" class="sm-add" data-stillmade-add="listingPhotos" aria-label="Add photos">`. StillMade opens its own picker and saves the files; they arrive through `onInput`. In an `sm-gallery` it takes the tile's shape. |
+| `sm-scrim` | Words over a photo or video, inside a positioned box such as an `sm-stage`: a see-through shade of the page under them, in every theme. `var(--scrim)` is the same shade for your own rules. |
+| `sm-glyph` | A small icon in `currentColor`: `play`, `pause`, `plus`, `close`, `check`, `chevron`, `chevron-left`, `chevron-right`, `upload`, `image`, `image-off`, `video`, `audio`, `text`, `spark`, `info`, `warning`, `spinner`. Works in standard views, which cannot use SVG. |
+
+**Function first.** When the person building a Block does not ask for a look,
+use the kit as is: they want it to work and be easy to use. When they name a
+design direction, follow it; the kit is the default, not a ceiling. Original
+designs keep `appearance: "original"`.
+
+## 2. Decide every sentence
+
+| If the words… | Then |
+| --- | --- |
+| aren't needed to finish the task (an intro, "how it works", the Block name again, a description of what is already visible) | Drop them. |
+| say what a glyph, thumbnail, swatch or sample can show | Show the picture. Keep one or two words under it. |
+| might help some people (what a setting does, a format limit) | Put them in a closed `sm-hint`, or secondary settings in a closed `sm-more`. |
+| report an error, a spending approval, a stale input or a destructive step | Keep them visible, in few words. Say what to do next. |
+
+Buttons say the action in the job's words, one to four of them ("Plan the tour",
+"Make 6 clips", "Export"), never "Make it". Status says the state in one to four
+words ("Making the clip", "Ready", "Needs approval").
+
+The button that makes something names what it makes ("Write", "Generate image",
+"Make video"), never "Run", "Run step", "Submit" or "Review cost", and says the
+progress word while it works ("Writing…").
+
+Credit prices come from StillMade, never from the Block. On a Step, StillMade's
+run button carries the price beside the verb ("Write · 1 credit"), with a chip
+before it when the model, quality or count can change; each choice there shows
+its own price. When a custom view starts paid work, StillMade's run review shows
+the same single priced button. Pressing a priced button runs at that price; a
+confirmation appears only when the server's price is higher than the one shown.
+Do not write credit numbers in the Block.
+
+## 3. Speak the job
+
+These are StillMade's defaults for every Block, and they apply wherever the
+person or the creator has not asked for something else. What they ask for wins.
+
+- **The job's words everywhere.** Bringing ("Your listing photos"), starting
+  ("Plan the tour"), working ("Moving through the kitchen, 4 of 9 rooms"),
+  done ("Your tour · 44 s") and problems ("No bathroom photo. Guests look for
+  one." with Add photo beside it). Never "Make it", "Run", "Submit",
+  "Process", "Processing", "Output" or "Result".
+- **Name the Step's button in `manifest.action`**:
+  `{"label":"Plan the tour","running":"Planning the tour…"}`. StillMade adds the
+  price ("Plan the tour · 1 credit"). A picture, video or sound made with AI
+  starts with Generate and says what ("Generate tour", "Generate voiceover");
+  cutting or rendering the person's own media says Make ("Make 6 clips").
+  Bare "Generate" or "Make" is not enough.
+- **The main button stands out.** One solid `sm-primary` per screen, in the
+  kit's ink, never restyled to the page's background or a ghost outline; every
+  other button is `sm-quiet` or an `sm-icon`. Close is an X icon, not the word.
+- **Quiet.** At most one line of guidance on a screen, only where the next
+  move is not obvious. No welcome text, tips under fields, tours or banners.
+  Anything more goes in the input's `description`, which StillMade shows
+  behind an (i).
+- **Say nothing about how the Block works.** No notes on where it runs (this
+  device, StillMade Desktop, the cloud), saving, syncing, recovery, accounts,
+  credits or where a file is kept: StillMade says what a person needs, as one
+  short notification, or nothing. Never a sentence on the page, and never the
+  same line under each item.
+- **References fill your inputs.** Every drop area in StillMade offers "Use a
+  reference": the person's saved photos, videos and notes fill the Step's
+  fields with no typing. Media inputs fill by kind, so take `video` or `asset`
+  wherever a clip works as well as a photo. Text inputs fill by their name and
+  label: name them plainly (`productName`, `website`, `brandColors`, `fonts`,
+  `voice`), and give the one that takes a reference's note a name such as
+  `details`, `notes` or `listingDetails`; when a note has to be split across
+  several fields StillMade does it free. Never build your own reference
+  picker or library upload.
+- **Files are tiles, added through StillMade.** A screen that holds an
+  input's files shows them as tiles (`sm-gallery`) ending in the kit's + tile,
+  `<button type="button" class="sm-add" data-stillmade-add="listingPhotos"
+  aria-label="Add photos">`. StillMade opens its own picker and saves the files
+  as its own tiles do; they arrive through `onInput`. From your own code call
+  `StillMade.addFiles("listingPhotos")` in a click. Never an
+  `<input type="file">` or an upload box of the Block's own. See
+  [Frame views](FRAME_VIEWS.md#adding-files-to-an-input).
+- **Days and times are picked, never typed.** Use the `date` type. StillMade
+  shows a calendar, and a list of times as well when the input is about a time
+  (a name such as `postAt` or `startsAt`, a label with Time, When or Starts, or
+  a value with a time). In a custom view use `<input type="date">` or
+  `type="datetime-local"`, never a text box for a date.
+- **Posting is its own Step.** Sending a result to Instagram, TikTok, email or
+  any app is a connector Step after the Block, and StillMade words its button
+  ("Post to Instagram"). A Block never posts from inside itself.
+- **Chat can do all of it.** Every button carries `data-stillmade-action`
+  and every field a label, so the project's Chat can press and fill them. The
+  button that runs the Block says `run` (StillMade's phone and desktop checks
+  press it with the fixture); every other button names what it does
+  (`data-stillmade-action="play sample"`). Chat reads the value with the
+  button's own words.
+
+## 4. Rules
+
+These are requirements for every author, person or model. Not all are checked
+automatically. An explicit request from the person can authorize a named
+exception, never unrelated technical UI.
+
+1. Show the thing being made, not a technical representation of it. No JSON
+   dumps, source editors, manifests, debug consoles or "Technical result"
+   panels unless the task is about source. A collapsed disclosure is still an
+   added surface. Every part shows at once (November 3, 2026): before the first
+   run the result's place is drawn in the shape and size of what is coming
+   (`<section class="sm-stage" data-ratio="9:16">` for a vertical clip, lines for
+   text, a player bar for sound), so the result fills a place the person already
+   sees instead of popping in somewhere unexpected. StillMade draws the Steps it
+   draws the same way (`ResultPlace`). On a wide screen what goes in sits on the
+   left and the result on the right, side by side (the kit's `sm-block` with an
+   `sm-stage` does this from 860px); they stack only on narrow screens and phones,
+   the result's place under the button (rule 16).
+2. One obvious next action. Seven or fewer choices in view; strong defaults.
+3. Choices people see or hear (voices, music, sounds, fonts, looks, colors,
+   templates, images) show a preview of each option: a thumbnail or a sample
+   to play, never a paid generation.
+4. One workspace. No cards inside cards, no dialogs as page layout, no second
+   title, step counter, Back/Next bar or generic "Workflow tools" menu.
+5. Keep the page in normal scroll flow. No sticky media, headers or control
+   strips unless the editing task needs a fixed timeline or inspector.
+6. Name secondary controls by purpose; no ambiguous settings gear.
+7. Icons come from the kit glyphs or your own files, with an accessible name
+   and tooltip. Never emoji, never a circle around an icon.
+8. Never hide spending approvals, failures or stale-source warnings for
+   neatness, and never discard drafts when collapsing controls.
+9. Text scene descriptions are planning notes, never a storyboard, frame review
+   or motion preview. Frame Review shows the exact images being approved.
+10. Compact: the whole Block fits one laptop screen (about 720 px tall)
+    without scrolling, and a 320 px phone without sideways scrolling. If it
+    does not fit, fold, shrink or move something; never add a section below.
+11. A short setting is one row, its label beside the control (the kit's
+    `sm-field` does this on any view wider than a phone). No card around a
+    single control.
+12. Status is a dot or a few words ("No narration yet"), never a paragraph.
+    The reason sits behind an `sm-hint`.
+13. Files are tiles: a saved file is a thumbnail or chip, and adding one is a
+    + tile, `<button class="sm-add" data-stillmade-add="<input>">`, which
+    opens StillMade's picker (or `StillMade.addFiles("<input>")` from your own
+    button). Never an `<input type="file">` or the browser's bare
+    "Choose File / No file chosen" picker, and no size limits in view until
+    a file is too big.
+14. Rare tools (update, schedule, history, reload) are named icon buttons
+    beside the action, never sections under the work.
+15. An (i) beside anything a newcomer could misread. A setting, status or
+    number whose effect is not obvious from its label ("Duplicates", "FPS",
+    "Commit", "Ready to render") gets a closed `sm-hint` next to it with one
+    or two plain sentences. On generated controls StillMade shows the input's
+    `description` as that (i), so write a `description` for every input that
+    needs one. Obvious controls ("Photos", "Tone") get none.
+16. Use the width. From 860 px wide, the kit puts the controls on the left
+    at a reading width (300–380 px) and the result (`sm-stage`, a direct
+    child of `sm-block`) fills the right, in its real shape. Under that the
+    page is one column in the page's order: the inputs, the action in
+    normal flow (rule 5: never a sticky bar), then the result's place under
+    it, so `sm-stage` comes after `sm-actions` in the markup. Keep the
+    inputs above the button short enough that a phone shows the button
+    without scrolling far; fold the rest into `sm-more`. Extra width goes to the result, never to wider text
+    fields. Before there is a result, the stage previews what will be made
+    from the inputs given so far, not an empty box. `data-layout="stack"`
+    keeps one column. StillMade zooms a view to fill its space and centers a
+    standard view narrower than its Step (by its margins only, so a margin
+    the view sets wins). An app that lays itself out (full-size canvas or
+    WebGL, its own scroll, pan or zoom, its own Ctrl/Cmd +/- keys) puts
+    `data-stillmade-layout="own"` on its outermost element, and StillMade
+    then never centers, zooms or takes those keys. StillMade plays every
+    `<video controls>` in its own player with full screen, and puts a
+    full-screen button on result pictures in `sm-stage` or `sm-gallery` and
+    on anything marked `data-stillmade-expand`; a `<video>` without
+    `controls` is the Block's own and is never touched.
+17. Settings sit side by side, next to what they change. Short settings are
+    an `sm-settings` grid, and three or four short options (Low / Med /
+    High, 16:9 / 9:16 / 1:1) are one `data-segmented` row, not big tiles.
+18. Lists fill the width at a small size. Input files are `sm-gallery
+    data-size="small"` tiles; many items (shots, scenes, rows) are an
+    `sm-list`, one line each with a thumbnail, one line of text and a short
+    fact, and tapping an item opens all of its fields in place. Extra width
+    means more items per row, never bigger cards.
+19. On a phone, chip and segment rows scroll sideways instead of wrapping,
+    long lists show their first three and "N more" (`sm-list data-peek`),
+    and long text shows five lines until tapped (`sm-clamp`).
+20. Nothing is lost when a Block gets smaller. Every control stays on the
+    screen, behind an (i), in `sm-more`, or inside the item it belongs to.
+    Compacting moves controls; it never deletes them.
+21. A picked option reads at a glance. The kit fills an `sm-choices` pick with
+    its ink (`--fg` behind `--bg` words, the same inversion as every
+    segmented control in StillMade); never restyle it to an outline, a tint or
+    the page's background. A locked row (`disabled`, or a person who can only
+    view) keeps its pick filled, fades the other options and does not react to
+    the pointer.
+22. Media that cannot show here (kept on another device, or it did not open)
+    keeps its place as a quiet `sm-media-off` tile in its own shape with the
+    `image-off` glyph, the reason in its `aria-label` and `title`. Never words
+    in its place:
+
+    ```html
+    <span class="sm-media-off" role="img" aria-label="On another device" title="On another device" style="--sm-photo-ratio:3/2">
+      <span class="sm-glyph" data-glyph="image-off" aria-hidden="true"></span>
+    </span>
+    ```
+23. One page per job (November 3, 2026). A job the person fills in and then
+    gets a result from is one Block on one page: the inputs and settings, a
+    cheap check before the expensive run (the script and a voice sample
+    before the video), then the result. The check is a second
+    `StillMade.run` on the same page, priced by StillMade on its own (Module
+    Blocks, "A check, then the expensive run, on one page"); it never becomes
+    a second Block or Step. A workspace the person works in for a while (a
+    CAD tool, a canvas, an editor) is its own Block, and turning what it made
+    into something else is the next one.
+
+## 5. What StillMade checks
+
+- Admission rejects a primary textarea of 12 or more rows when no task
+  presentation (stage, media, list or `StillMade.render`) is detected
+  (`INTERFACE_DESIGN_RULES`).
+- Admission warns about more than eight visible controls, more than seven
+  ungrouped options, more than one `h1`, a visible paragraph over twenty words,
+  a word dropdown for something people see or hear, a bare browser file
+  picker, and a size limit printed in view.
+- Readiness notes settings left loose on the page: three or more `sm-field`
+  outside an `sm-fields`, `sm-settings`, `sm-more` or `sm-list` group. The kit
+  gives that group its own surface, so the inputs, the settings and the result
+  read apart; the SDK gate and StillMade's builder send the note back like any
+  Wording note.
+- Admission warns about the compact rules it can see in the source: a short
+  input or select whose label sits above it outside `sm-field` / `sm-settings`
+  (a `<br>` between them, or a label made `display: block`); a heading,
+  legend or `<details>` summary titled Update, Schedule, History, Reload or
+  Versions, which should be an icon button beside the action; and more than
+  eight visible top-level rows besides the stage. The row count is an estimate:
+  a static check cannot measure height. StillMade's builder preview measures the
+  real one and says when the view is taller than one laptop screen (720px) at
+  the Desktop size.
+- Admission also warns, and `stillmade-block ready` fails the "UI works" check
+  (DOD-15), when a button says "Run", "Run step" or "Submit", when the
+  interface shows a credit price, or when it has a page heading
+  (`blockKitProblems`; the failing rules are `BLOCK_KIT_READINESS_RULES`). StillMade's own Block builder also sends back a custom
+  view that is not built from `sm-block`, unless the person asked for their
+  own look (`appearance: "original"`).
+- Admission warns, and readiness lists a "Wording" limitation, when a button
+  says "Make it", "Generate", "Create", "Process" or "Do it"; when progress
+  says "Processing", "Loading" or "Working"; when a visible line explains where
+  the Block runs or how it saves; when a date is typed into a text box; when
+  the CSS turns `sm-primary` into a background-coloured button; when the CSS
+  takes the ink fill off a pick (`.sm-choices label:has(input:checked)` with a
+  transparent or page-coloured background, or the ink as its text colour); and
+  when the page or a string in its code says where a file is kept ("Only on
+  this device", "Not on this device"). Clear
+  every one before you hand the Block back, unless the person asked for those
+  words. They never refuse a release.
+- The host supplies the Project Type step bar and omits its own title and frame
+  around custom views, and does not add a "Technical result" disclosure.
+- HTML, JavaScript, permission and appearance validation are separate checks.
+  Simplicity never bypasses safety or approval.
+
+The SDK exports the ordered principles as `BLOCK_INTERFACE_PRINCIPLES` and the
+kit vocabulary as `BLOCK_KIT_CLASSES`. `INTERFACE_DESIGN_CONVENTIONS`,
+`INTERFACE_DESIGN_PRINCIPLES` and `INTERFACE_AUTHORING_RULES` remain as
+compatibility names for the same list.
+
+## Existing Blocks
+
+Pinned Blocks can still contain nested panels and text-only plans; the kit does
+not redesign them. Move a Block to the kit through a new versioned release and
+an explicit upgrade, following the
+[SDK update procedure](https://stillmade.shop/block-sdk/PASTE_TO_LLM.md#updating-existing-blocks-through-the-sdk).
+Never rewrite immutable releases or silently change a saved workflow's pins.

package/docs/build/javascript.md

@@ -0,0 +1,63 @@
+# JavaScript Blocks
+
+Computation code may use `StillMade.emit(name, value)` instead of returning an
+output object. Names must be declared outputs; emit each once, and do not combine
+emission with a return value or cooperative pending result. Emissions remain
+inside the sandbox until final host validation and normal result acceptance.
+`StillMade.resolveRequirement(inputName)` reads a declared input from the fixed
+host-validated snapshot and returns `{resolved:true, requirement, value}` or
+`{resolved:false, requirement}` for an absent optional input. Undeclared names
+throw; this method does not search sources or call Chat.
+
+`StillMade.getProjectContext()` returns an isolated snapshot of declared
+context-bound inputs, keyed by their `context` field names. An optional declared
+field argument reads one value; undeclared fields throw and absent optional
+values return `undefined`. It does not enumerate the whole project or bypass
+host permissions, and it does not fetch newer values during a run.
+
+`StillMade.validate(value, schema)` returns a boolean for supported JSON/schema
+validation only. It does not establish semantic correctness, media validity,
+permissions, or provenance. Final host output validation remains mandatory.
+These computation helpers are not available to `view.javascript`. Isolated
+computation code also has `StillMade.requestFromUser` and `StillMade.requestFromChat`
+(see `UNIVERSAL_RESOLVER.md`) and `StillMade.patchProject` (reviewable workspace-edit
+proposals).
+See `JAVASCRIPT_RESULTS.md` for state, continuation and permission boundaries.
+
+Create an editable JavaScript block with:
+
+```sh
+node packages/block-cli/cli.js create ./my-js-block javascript
+node packages/block-cli/cli.js test ./my-js-block
+node packages/block-cli/cli.js pack ./my-js-block ./my-js-block.stillmade.json
+```
+
+Set `manifest.runtime` to `javascript`. The source file is `src/run.js`, packed
+as `{manifest,code,tests}`. Write a synchronous function body: `input` contains
+validated named inputs; return an object whose keys match declared outputs.
+For example, with a text input and text/words outputs:
+
+```js
+const text = input.text.trim();
+return { text, words: text ? text.split(/\s+/).length : 0 };
+```
+
+Use `await runPackageAsync(package, input)` from the SDK to dispatch either runtime.
+The older synchronous `runPackage` remains recipe-only. In browsers, invoke the
+async API inside a disposable worker; the app does this automatically. On Node,
+the SDK creates and terminates a separate worker for every JavaScript execution.
+The downloadable SDK includes its pinned QuickJS WASM runtime and dependency
+licenses, so these examples run without installing packages or accessing a network.
+
+The guest has standard QuickJS JavaScript built-ins. It has no DOM, browser storage,
+fetch, Node globals, timers, module loader, filesystem, secrets, or host callbacks.
+An asset reference is data, not file access. npm packages and imports are unsupported.
+Promises are not awaited; return synchronously. Values cross through JSON and
+are validated against output ports. Avoid Date/randomness in behavior fixtures.
+
+Limits per run: 256 KiB source, 4 MiB serialized input and output, 500 ms guest
+execution, 16 MiB guest heap, 512 KiB stack, and a fixed 32 MiB WASM memory.
+Node adds a five-second worker watchdog and at most four concurrent executions;
+app workers have a 15-second outer watchdog. Each package fixture suite has a ten-second deadline (callers may shorten it);
+all embedded packages share a fifteen-second project-type deadline. Timeouts, allocation failures, invalid outputs and syntax errors
+fail the run; no partial output is committed. Each run receives a fresh VM.

package/docs/build/local-preview.md

@@ -0,0 +1,61 @@
+# Preview with hot reload
+
+`stillmade-block dev <folder>` opens a local preview at `http://127.0.0.1:4800`
+(`--port` changes it). The page is StillMade's own view host: the same sandbox
+page, bridge, response policy, theme, run limits and guard that run your
+interface in the app, so what works here works there.
+
+- Your interface (standard or frame view) runs with the first fixture's input.
+  Pick another fixture, switch Light, Dark and White, and try phone, tablet and
+  full widths. The **Input data** tab of the panel below the Block shows that
+  input as JSON. An edit there applies when you leave the box (click outside it
+  or press Tab), not as you type; the view then hears it through `onInput`. Text
+  that is not one JSON object is named under the box and not applied.
+- `StillMade.run` runs the Block on your machine with the SDK runtime. As on a
+  project Step, the inputs the view leaves out are the current input's, so
+  `StillMade.run({make: 'check'})` still gets the example's photos; what the
+  view passes is kept in the input. Hosted
+  operations, files, network, connections and storage are answered by
+  [stand-ins](testing.md), and stand-in media (images, audio, video)
+  previews in the view. Shared view state (`updateShared`) is kept in the page.
+  The view's `addFiles`, `removeFile` and `moveFile` change the input's files
+  here as they change a Step's.
+- Saving any file the package reads reloads the preview, keeping the input and
+  shared state. With `--build "npm run build"`, saving any other source file
+  (such as `src/view.jsx`) runs the build first, then reloads.
+- The console lists every run, the module's `stillmade.log` lines, each
+  stand-in that answered, reloads, build output and errors from the view.
+- The server listens on this machine only, refuses other host names and other
+  sites, and never contacts StillMade or a provider. Paid runs, sign-ins and
+  keys happen only in StillMade, after you import the Block.
+
+### Live link to your account
+
+`stillmade-block dev <folder> --live` also prints a link to StillMade's Import
+page. Open it while signed in and choose **Connect**: each time you save, the
+packed Block (what `pack` would write) opens in StillMade's usual import review
+with its checks and preview, and confirming installs that version in your
+account, as a new revision of the same build. Use it in a project to run it with
+real hosted operations, files and connections; every paid step shows its price
+and asks first, as for any Block.
+
+- Nothing is installed or published without your confirmation in the review.
+- Only the StillMade site can read the link, and only with the random key in it,
+  which changes each time `dev` starts. `--site` sets another StillMade address
+  (https). Stop the link with **Disconnect** or by stopping `dev`.
+- The browser may ask once whether StillMade may reach a local address.
+
+## Templates
+`stillmade-block create <folder> <template>` writes a complete folder that validates and tests offline:
+
+| Template | What it starts |
+| --- | --- |
+| `recipe` (default), `image`, `stateful` | Built-in steps with no code; memory between runs |
+| `javascript` | A few lines of sandboxed JavaScript |
+| `module`, `module-wasm` | Modern JavaScript modules in a Worker, with WebAssembly |
+| `module-hosted` | A module calling hosted text and image generation as tools |
+| `view-react`, `view-html` | A frame view in React (bundled with esbuild) or plain web code |
+| `text`, `image-generate`, `video-generate`, `speech`, `music`, `sfx`, `transcribe`, `describe-image`, `analyze-media`, `web-fetch`, `web-research`, `timeline-proposal` | One hosted operation each, on the person's credits |
+| `outside-api`, `connection` | An outside API with the person's own key; a published adapter with their sign-in |
+| `storage` | Values kept across runs in project storage |
+| `trigger-media`, `trigger-webhook`, `trigger-schedule` | Blocks that run on their own once the project owner turns them on |

package/docs/build/media-analysis.md

@@ -0,0 +1,27 @@
+# Hosted media analysis
+
+`media.analyze` asks StillMade's media vision a question about saved media and
+returns structured evidence. Declare one `video`, `image` or `image[]` (one to
+four images) input, one `text` or `json` output and
+`permissions.capabilities: ["media.analyze"]`. A video Block may bind two
+optional `number` inputs as a time range to look at closely (at most 12 seconds):
+
+```json
+{"schemaVersion":1,"operation":"media.analyze","media":{"$input":"clip"},
+ "question":"Is the product logo clearly visible, and when?",
+ "range":{"start":{"$input":"start"},"end":{"$input":"end"}},"output":"report"}
+```
+
+StillMade reads the media from the runner's own library (never from another
+account or an arbitrary URL), samples a video into a timestamped contact sheet
+or uses the still image, and asks the vision model the Block's question (1 to
+2,000 characters). A `json` output receives
+`{"schemaVersion":1,"items":[{"kind","summary","timeline","observations","detectedText","issues","confidence","range"?}]}`
+with timestamps in seconds; each list holds up to 20 entries. A `text` output
+receives the summaries (numbered when there are several images).
+
+Each analyzed image or video is one priced call, paid with StillMade credits;
+the quote lists the price for every fixture and the sample. Media that cannot
+be read (not saved in the library, too large, or undecodable) is refunded. The
+offline SDK includes `packages/block-sdk/media-analysis-example.js`, exporting
+`mediaAnalysis`.