stillmade-sdk 0.1.42 → 0.1.44

package/docs/build/media.md

@@ -0,0 +1,400 @@
+# Images and media references
+
+Portable references are `{assetId,versionId,kind}`; a reference is not an absolute
+file path. Current pure image operations require a decoded fixture/preview image:
+`{width,height,data:[R,G,B,A,...]}` with 0–255 integer channels, up to 1 megapixel.
+Large production media must use a host media adapter; this SDK does not pretend
+to transcode an arbitrary asset reference. Line thickening uses a square dilation
+kernel and thresholded luminance; it returns a new RGBA image.
+
+Connected Project Type previews include a small, temporary media bridge. If an
+image-producing Block returns pixels and the next input accepts an asset,
+StillMade encodes a real PNG data URL in memory and supplies a preview media
+reference. If a later image input receives that same exact generated reference,
+the bridge supplies copied pixels to image-processing code. Original pixel
+outputs remain visible as pixel previews; direct image-to-image connections do
+not need this conversion.
+
+This behavior is shared by the browser's connected preview, CLI `preview`, and
+Project Type admission tests. It does not upload media, fetch external URLs, or
+create project assets. Only references generated by that preview session can be
+hydrated; changing their kind, asset/version identity, URL or semantic role fails.
+Optional dimensions and labels may be omitted or changed; the private pixel copy
+remains authoritative. Other references remain
+inert references for the caller's supported host runner. Encoding and private
+cache costs share the existing 4 MB sample budget and preview deadline, so use
+small fixtures. Production execution uses its normal authorized media storage
+and decoding path instead of these temporary references.
+
+## Saved media collections
+Use an `asset[]`, `audio[]` or `video[]` input to collect media files with
+standard controls. Inside a project, these controls upload, select, order and
+remove files without custom host code. Project uploads are saved before the
+input is published, with exact per-file receipts bound to the Block version.
+Compatible direct remixes retain uploaded media. Builder previews use temporary
+local files; upload in a project for durable use. Project controls admit up to
+64 list entries and 50 MiB per original file, subject to the shared format table.
+The sandbox receives typed references, never upload credentials or local paths.
+
+[Import media 2.0.0](https://stillmade.shop/block-sdk/examples/import-media.stillmade-block) is a complete
+portable example. Its owned JavaScript preserves metadata and selection order,
+optionally filters media kinds or removes exact duplicate references, and returns
+an `asset[]` output for subsequent Blocks. It does not transcode media or claim
+rights over user files. Its license covers the original Block implementation.
+Empty selections return an empty list. The native legacy upload node remains
+available to old placements; new SDK placements use the standard sandbox.
+
+Validate and test the downloaded archive with the same public CLI:
+
+```sh
+node packages/block-cli/cli.js validate import-media.stillmade-block
+node packages/block-cli/cli.js test import-media.stillmade-block
+node packages/block-cli/cli.js remix import-media.stillmade-block my-import.stillmade-block
+node packages/block-cli/cli.js test my-import.stillmade-block
+```
+
+### Mandatory host-controlled exports
+
+Blocks return typed results or `file-bundle` outputs for StillMade to deliver.
+Do not create download links, invoke save-file pickers, open export destinations,
+or implement a separate export/paywall/referral bypass. The upload admission
+report requires **Host-controlled exports** (`host-export-1`), alongside existing
+sandbox and interface checks. A passing static check is not a delivery receipt.
+StillMade owns the current export policy for all creators; it may add a referral
+step, checkout or other requirement without changing your Block. It can also
+require the StillMade watermark on exports from accounts without a paid plan;
+StillMade draws it while rendering videos and delivering images, so do not add
+your own. Block pricing and export access are separate. Never claim payment or referral completion from
+Block code. Native integrations must declare the host export service and route
+delivery through it; an extracted source folder does not satisfy this boundary.
+
+## Image-processing example
+```json
+{
+  "manifest": {
+    "schemaVersion": 1,
+    "license": "MIT",
+    "provenance": {
+      "notice": "MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"
+    },
+    "sdkVersion": "0.1.0",
+    "id": "example.thicken-lines",
+    "action": {
+      "label": "Thicken lines",
+      "running": "Thickening lines…"
+    },
+    "version": "1.0.1",
+    "name": "Thicken line art",
+    "description": "Expands dark outlines in an image while preserving surrounding colors, creating a new image for the next production step.",
+    "kind": "task",
+    "runtime": "recipe",
+    "inputs": {
+      "image": {
+        "type": "image",
+        "primary": true,
+        "semantic": "source_image",
+        "required": true,
+        "description": "Line-art image whose dark outlines should be expanded."
+      },
+      "thickness": {
+        "type": "integer",
+        "default": 2,
+        "min": 1,
+        "max": 8,
+        "semantic": "line_thickness",
+        "required": false,
+        "description": "Number of pixels by which to expand dark outlines."
+      },
+      "threshold": {
+        "type": "number",
+        "default": 100,
+        "min": 0,
+        "max": 255,
+        "semantic": "darkness_threshold",
+        "required": false,
+        "description": "Brightness threshold used to identify dark outline pixels."
+      }
+    },
+    "outputs": {
+      "image": {
+        "type": "image",
+        "primary": true,
+        "semantic": "processed_image",
+        "description": "A new image with expanded dark outlines."
+      }
+    },
+    "permissions": {
+      "project": [],
+      "network": [],
+      "filesystem": [],
+      "secrets": []
+    },
+    "ui": [
+      {
+        "control": "asset",
+        "port": "image"
+      },
+      {
+        "control": "slider",
+        "port": "thickness"
+      },
+      {
+        "control": "slider",
+        "port": "threshold"
+      }
+    ]
+  },
+  "recipe": {
+    "schemaVersion": 1,
+    "steps": [
+      {
+        "id": "outlines",
+        "op": "image.thicken-lines",
+        "args": {
+          "image": {
+            "$input": "image"
+          },
+          "thickness": {
+            "$input": "thickness"
+          },
+          "threshold": {
+            "$input": "threshold"
+          }
+        }
+      }
+    ],
+    "outputs": {
+      "image": {
+        "$step": "outlines"
+      }
+    }
+  },
+  "tests": [
+    {
+      "name": "One dark point expands to a 3×3 square",
+      "input": {
+        "image": {
+          "width": 5,
+          "height": 5,
+          "data": [
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            0,
+            0,
+            0,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255
+          ]
+        },
+        "thickness": 1
+      },
+      "expected": {
+        "image": {
+          "width": 5,
+          "height": 5,
+          "data": [
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            0,
+            0,
+            0,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255,
+            255
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+## Host boundary
+The host resolves a selected image into RGBA before execution and stores accepted output as a new media version. A guest receives no filesystem path or network access. Large files require an explicit host-side conversion or resized copy.
+
+See [batch execution](../project-types/batches.md) for whole-scene and project-wide processing.

package/docs/build/mobile-ui.md

@@ -0,0 +1,106 @@
+# Mobile-compatible Block UI
+
+# Mobile-compatible Block UI
+
+Build one Block contract for every size. Inputs, outputs, state, actions,
+permissions, and runtime do not change when the interface becomes compact.
+StillMade reorganizes standard controls automatically and keeps custom views in
+the existing opaque sandbox.
+
+## Standard UI
+
+Prefer `manifest.ui` and `manifest.uiLayout`. The host owns field sizing, focus,
+touch targets, stacked preview/results, tab overflow, safe-area spacing, and
+software-keyboard behavior. Use `uiLayout` only to group complete inputs and
+outputs; do not create a second mobile manifest or split an editor into tiny
+Blocks.
+
+Tabs and sections must retain every essential input and output. A compact layout
+may put secondary tools behind a labelled section or sheet, but the primary
+action and focused field must remain reachable. Resizing the preview does not run
+the Block and must not reset its values, selection, state, progress, or result.
+
+## Custom UI
+
+Custom HTML, CSS, and JavaScript continue to use `view` and `StillMade.run`.
+Design from the view container rather than a device name:
+
+```css
+.workspace { container: block-workspace / inline-size; min-width: 0; }
+.layout { display: grid; grid-template-columns: minmax(0, 2fr) minmax(240px, 1fr); }
+@container block-workspace (max-width: 600px) {
+  .layout { grid-template-columns: minmax(0, 1fr); }
+}
+```
+
+The sandbox supplies viewport-fit, safe-area padding, readable form defaults,
+44-pixel ordinary controls, media containment, and focus styling. Authored CSS
+still owns specialized workspace layout. A 320 CSS-pixel phone viewport leaves
+less than 320 pixels inside the host's preview gutters. Size from the embedded
+view's actual container, avoid a 320-pixel minimum width, wrap long labels, and
+isolate intentional canvas/timeline panning from
+the surrounding toolbar. A `<video controls>` gets StillMade's player, whose
+44-pixel controls a tap shows for 3 seconds (a first tap never starts playback),
+and a result picture's full-screen button shows for 3 seconds after a tap on it. Provide visible buttons or menus for actions otherwise
+available by hover, drag, right-click, or keyboard shortcut. Label fields and
+announce loading, errors, and completed output with `role="status"`,
+`role="alert"`, or `aria-live` as appropriate. For deterministic custom-view
+checks, set `data-stillmade-state="loading"`, `"error"`, or `"success"` on the
+visible result area as each state occurs. The browser profile runs the local
+success fixture, then injects a local executor failure to exercise the same
+view's error path without calling a provider. Standard controls receive the
+same failure and must show their error result. A permanently mounted live region
+does not demonstrate that an error was actually shown. If the test never
+reaches a state, phone support remains unverified rather than inferred.
+
+The maintained `examples/custom-interface.stillmade.json` demonstrates one
+custom workspace whose settings and result stack from the same state and action
+contract.
+
+For deterministic browser checks, mark a custom form control with
+`data-stillmade-input="portName"` so the phone profile can enter the package's
+test fixture through the real UI before pressing its run action. This marker
+does not change the Block's input contract or grant access to host services.
+For a text-bearing object fixture such as `{brief:{text:"…"}}`, the profile
+enters its `text` into the marked text field, then presses the button marked
+`data-stillmade-action="run"` (or the view's only button). Every button carries
+`data-stillmade-action` so Chat can press it: `run` on the button that runs the
+Block, and what it does on every other button (`data-stillmade-action="play sample"`).
+The existing `data-stillmade-share` marker is also recognized for shared text
+fields. A custom view without a reachable mapped control must not be counted
+as having passed its fixture's success interaction.
+
+## Preview and authoritative validation
+
+The Create preview includes Compact (320), Phone (390), Tablet (768), phone
+landscape (844 × 390), and Desktop (1280) container presets. Changing a preset
+only changes available space. Its quick check helps find immediate host overflow
+and small touch targets; imported and published packages still run the
+authoritative profile in the real Block/Project Type host.
+
+The SDK `testPlatforms` gate records the exact package digest plus SDK, renderer,
+and check versions. A trusted browser adapter covers Light, Dark, and White at
+320, 390, 768, 1280, and phone landscape. It checks the main touch task, empty,
+populated, loading, error, success, long-label and enlarged-text states, and
+continuity through resize/rotation and panel toggles. Custom views must visibly
+enter each claimed state during the check; source markup alone is not evidence
+of a working error path. Fixture execution is local
+or mocked; the mobile UI profile never authorizes a provider call or spends
+credits.
+
+Reports supplied inside a package are ignored. A changed package or changed
+renderer/check version needs a new report. Failures name the affected view,
+control, and CSS size and remain repairable in draft preview. Passing the profile
+does not make an unavailable desktop binary, local GPU, provider, or credential
+available on a phone; runtime capability checks remain separate.
+
+For a local preview build, `node scripts/platform-tests/run.mjs --engine=chromium --require-complete` uses that same trusted embedded profile
+and saves per-size captures and a digest-bound report. Firefox and WebKit runs
+are exploratory layout checks; they cannot supply the profile's state and
+continuity evidence. A report from any local command does not grant a
+Marketplace support claim or replace StillMade's server-owned import review.
+
+Before public release, StillMade also smoke-tests representative shared UI in
+real iOS Safari and Android Chrome. Gesture-heavy custom editors require a
+focused real-device check. Those operational checks complement the deterministic
+gate; they are not inferred from an author claim.