stillmade-sdk 0.1.42 → 0.1.44

package/docs/reference/first-party-blocks.md

@@ -0,0 +1,40 @@
+# First-party Blocks
+
+## First-party Blocks
+The latest version of each Block bundled with the SDK, generated from the packages themselves. Connect to a port by matching its type and meaning. A port marked "project context only" reads the project and cannot receive a connection from another Step; a `workspace` Block is never connected automatically.
+
+| Block | Name | Kind | Inputs | Outputs |
+| --- | --- | --- | --- | --- |
+| `sm.ai-decide` 1.0.0 | AI decide | task | `data` text (external_data) · primary; `rules` text (decision_rules) | `decision` object (ai_decision) · primary |
+| `sm.ai-write` 1.0.0 | AI write | task | `data` text (external_data) · primary; `instructions` text (writing_instructions) | `text` text (written_message) · primary |
+| `sm.board-editor` 2.2.11 | Whiteboard | workspace | `board` board-document (whiteboard_document) · project context only · primary; `updatedBoard` board-document (whiteboard_document); `commit` boolean (apply_changes); `action` text (whiteboard_action); `presenterPrompt` text (presenter_prompt); `generatedImage` image (image); `versions` metadata[] (revision_history) · project context only; `presence` metadata[] (collaborator_presence); `assets` asset[] (project_media) · project context only | `board` board-document (whiteboard_document) · primary; `edit` workspace-edit (workspace_edit); `presenterAction` approval (portable_media_action); `qualityAction` approval (portable_media_action); `renderAction` approval (portable_media_action); `actionEdit` workspace-edit (workspace_edit); `qualityReport` metadata (quality_report); `editorTimeline` timeline (editor_handoff); `revision` metadata (revision_event) |
+| `sm.captions` 2.0.0 | Captions | editor-extension | `transcript` transcript · primary; `projectTranscript` transcript · project context only; `timeline` timeline · project context only; `text` text; `start` number; `duration` number; `highlightColor` text; `animation` text | `edit` timeline-edit · primary |
+| `sm.character` 2.0.1 | Character reference | workspace | `input` text (character_description) · primary; `name` text (character_name); `role` text (character_role); `appearance` text (character_appearance); `personality` text (character_personality) | `output` character (character_reference) · primary |
+| `sm.compare` 2.0.2 | Compare assets | workspace | `imageA` image (comparison_image_a) · primary; `imageB` image (comparison_image_b); `selection` text (comparison_selected_image); `position` integer (comparison_split_position) | `output` image (selected_comparison_image) · primary |
+| `sm.connect-app` 1.0.0 | Connect an app | task | `app` text (connected_app) · primary | `result` object (external_data) · primary |
+| `sm.contact-fields` 1.0.0 | Contact fields | task | `record` object (external_data) · primary | `email` text (contact_email) · primary; `first_name` text (contact_first_name); `last_name` text (contact_last_name); `full_name` text (contact_full_name); `phone` text (contact_phone); `company` text (contact_company); `city` text (contact_city); `other_answers` text (contact_other_answers) |
+| `sm.edit-assistant` 2.0.2 | Edit Assistant | task | `timeline` timeline (timeline) · project context only · primary; `selection` timeline-range (timeline_range); `request` text (edit_request) | `edit` timeline-edit (timeline_edit_proposal) · primary |
+| `sm.editor` 2.2.12 | Editor | workspace | `editor` timeline (editor_timeline) · project context only · primary; `assets` asset[] (legacy.asset-list.assets) · project context only; `updatedEditor` timeline (legacy.timeline.updatededitor); `commit` boolean (legacy.boolean.commit); `action` text (legacy.text.action); `renderFps` integer (legacy.integer.renderfps); `renderResolution` integer (legacy.integer.renderresolution); `renderQuality` text (legacy.text.renderquality) | `editor` timeline (editor_timeline) · primary; `edit` workspace-edit (legacy.workspace-edit.edit); `mediaAction` approval (portable_media_action) |
+| `sm.export-audio` 2.0.0 | Export audio | task | `input` timeline (timeline) · primary; `renderFps` text (render_fps); `renderResolution` text (render_resolution); `renderQuality` text (render_quality); `projectTimeline` timeline (timeline) · project context only | `mediaAction` approval (portable_media_action); `output` audio (rendered_audio) |
+| `sm.export-timeline` 2.0.0 | Export timeline | editor-extension | `timeline` timeline · project context only · primary; `assets` asset[] · project context only; `blueprint` bible · project context only; `shotPlan` shot-plan · project context only; `metadata` metadata · project context only; `title` text; `format` text | `download` file-bundle · primary |
+| `sm.export-video` 2.1.0 | Export video | task | `input` timeline (timeline) · primary; `media` asset[] (project_media); `narration` audio (narration_audio); `renderAspect` text (render_aspect); `renderFps` text (render_fps); `renderResolution` text (render_resolution); `renderQuality` text (render_quality); `projectTimeline` timeline (timeline) · project context only; `projectShotPlan` shot-plan (production_shot_plan) · project context only | `mediaAction` approval (portable_media_action); `output` video (rendered_video) |
+| `sm.final-edit` 2.0.2 | AI Final Edit | task | `timeline` timeline (timeline) · project context only · primary; `direction` text (edit_direction) | `edit` timeline-edit (timeline_edit_proposal) · primary |
+| `sm.generate-image` 2.1.0 | Generate image | task | `input` text · primary; `photos` image[] (reference_image) | `output` image · primary |
+| `sm.generate-video` 2.0.1 | Generate video | task | `prompt` brief (video_generation_brief) · primary | `video` video (generated_video) · primary |
+| `sm.grade` 2.0.2 | Color grade | editor-extension | `timeline` timeline (editor_timeline) · project context only · primary; `clipIds` text[] (timeline_clip_ids); `look` text (color_grade_look); `adjustments` json (color_grade_adjustments) | `edit` timeline-edit (timeline_edit) · primary |
+| `sm.import-media` 2.0.2 | Import media | task | `files` asset[] (legacy.asset-list.files) · primary; `include` text (legacy.text.include); `duplicates` text (legacy.text.duplicates) | `assets` asset[] (legacy.asset-list.assets) · primary |
+| `sm.location` 2.0.1 | Location reference | workspace | `input` text (location_description) · primary; `name` text (location_name); `visualDetails` text (location_visual_details); `timeOfDay` text (location_time); `atmosphere` text (location_atmosphere) | `output` location (location_reference) · primary |
+| `sm.meta-creative` 1.0.0 | Meta ad creative | task | `upload` object (external_data) · primary; `message` text (ad_primary_text); `website_url` text (ad_destination_url); `page_id` text (facebook_page_id); `call_to_action` text (ad_call_to_action) | `creative` object (meta_ad_creative) · primary |
+| `sm.motion-graphics` 2.0.0 | Motion graphics | editor-extension | `timeline` timeline (timeline) · primary; `projectTimeline` timeline (timeline) · project context only; `plan` json (motion_graphics_plan) | `timeline` timeline (timeline) · primary; `edit` workspace-edit (editor_workspace_edit) |
+| `sm.panel-strip` 2.4.2 | Image Panels | workspace | `panels` panel-document (image_panel_document) · project context only · primary; `transcript` transcript (timed_transcript) · project context only; `script` script (narration_script) · project context only; `narrationScript` script (narration_script); `narrationTiming` transcript (timed_transcript); `blueprint` bible (production_blueprint) · project context only; `updatedPanels` panel-document (image_panel_document); `commit` boolean (apply_changes); `generatedImage` image (image); `targetPanelId` text (panel_id); `attachGeneratedImage` boolean (boolean); `action` text (host_action); `stockQuery` text (stock_query); `generatedImages` image[] (image_list) | `panels` panel-document (image_panel_document) · primary; `edit` workspace-edit (workspace_edit); `stockAction` approval (portable_media_action); `qualityAction` approval (portable_media_action); `renderAction` approval (portable_media_action); `stockAsset` asset (licensed_asset); `stockImage` image (licensed_stock_image); `qualityReport` metadata (quality_report); `generationPlan` metadata (generation_plan); `generateAction` approval (portable_media_action); `generatedImage` image (generated_image); `batchGenerateAction` approval (portable_media_action); `generatedImages` image[] (generated_image_list) |
+| `sm.photo-notes` 1.1.0 | Photo notes | task | `photos` image[] (photo_set) · primary | `notes` text (photo_notes) · primary |
+| `sm.pipeline` 2.2.6 | Canvas | workspace | `canvas` pipeline (canvas_document) · project context only · primary; `assets` asset[] (project_assets) · project context only; `versions` metadata[] (asset_versions) · project context only; `updatedCanvas` pipeline (canvas_document); `commit` boolean (canvas_commit_intent); `generatedImage` image (generated_image_version); `addGeneratedImage` boolean (attach_generated_image); `generatedImageTitle` text (generated_image_title); `generatedVideo` video (generated_video_version); `addGeneratedVideo` boolean (attach_generated_video); `generatedVideoTitle` text (generated_video_title); `generatedAudio` audio (generated_audio_version); `addGeneratedAudio` boolean (attach_generated_audio); `generatedAudioTitle` text (generated_audio_title); `connectionProposal` json (context_connection_proposal); `applyContextConnections` boolean (context_connection_intent) | `canvas` pipeline (canvas_document) · primary; `edit` workspace-edit (canvas_edit_proposal) |
+| `sm.rough-cut` 2.0.2 | Rough Cut | task | `timeline` timeline (timeline) · project context only · primary; `clipIds` text (timeline_clip_selection); `startAt` number (timeline_start_seconds); `gap` number (timeline_clip_gap_seconds) | `edit` timeline-edit (timeline_edit_proposal) · primary |
+| `sm.score` 2.0.0 | Audio scoring | workspace | `timeline` timeline (timeline) · primary; `projectTimeline` timeline (timeline) · project context only; `audio` audio; `stockAsset` asset (licensed_asset); `audios` audio[]; `plan` json (audio_score_plan) | `timeline` timeline (timeline) · primary; `edit` workspace-edit (editor_workspace_edit) |
+| `sm.style` 2.0.1 | Style reference | workspace | `input` text (visual_style_direction) · primary; `name` text (style_name); `palette` text (color_palette); `lighting` text (lighting_direction); `camera` text (camera_direction) | `output` style (visual_style_reference) · primary |
+| `sm.transition` 2.0.2 | Transition | editor-extension | `timeline` timeline (editor_timeline) · project context only · primary; `clipIds` text[] (timeline_clip_ids); `transition` text (timeline_transition_type); `duration` number (timeline_transition_duration); `soundOn` boolean (timeline_transition_sound_enabled); `soundId` text (timeline_transition_sound_id) | `edit` timeline-edit (timeline_edit) · primary |
+| `sm.video-assets` 2.1.4 | Video Assets | workspace | `assets` asset[] (media_collection) · project context only · primary; `versions` metadata[] (media_version_history) · project context only; `incoming` asset[] (media_collection); `kind` text (media_filter); `selectedIds` text (media_selection); `selectedVersions` text (media_version_selection) | `output` asset[] (production_media) · primary |
+| `sm.voiceover` 2.1.6 | Voiceover | workspace | `input` script (narration_script) · primary; `take` audio (narration_audio); `library` asset[] (project_media) · project context only; `timing` transcript (timed_transcript) · project context only | `output` audio (narration_audio) · primary |
+| `sm.when` 1.1.0 | Automation | task | `event` object (workflow_event); `start` object (automation_start); `only_if` text (automation_condition) | `item` object (external_data) · primary; `trigger` object (automation_trigger); `check` object (ai_decision) |
+| `sm.write-summary` 1.0.0 | Write summary | task | `data` text (external_data) · primary | `summary` text (summary_report) · primary |
+| `stillmade.generate` 1.0.0 | Generate | task | `prompt` text (generation_prompt) · primary; `mode` text (generation_mode); `model` text (generation_model); `aspectRatio` text (aspect_ratio); `size` text (render_resolution); `quality` text (render_quality); `duration` integer (duration_seconds); `sound` boolean (generate_audio); `count` integer (generation_count); `avoid` text (negative_prompt); `seed` integer (generation_seed); `references` image[] (reference_image); `startFrame` image (first_frame); `endFrame` image (last_frame) | `media` asset[] (generated_media) · primary; `notMade` text (generation_failures) |

package/docs/reference/generation-models.md

@@ -0,0 +1,59 @@
+# Generation models
+
+## How models are used
+Capability Blocks (`image.generate`, `video.generate`, `audio.music`, `audio.sfx`, `audio.speech`) and JavaScript Blocks (the `media.generate` action) can use every model below, the same catalog the app's own Blocks use. Users pay with StillMade credits at StillMade's price; a Block declares default settings and the user can change them before running. A setting a model has no knob for is `"default"`.
+
+## Image models
+| Model | Name | Aspect ratios | Resolutions | Qualities | Reference images | Seed |
+| --- | --- | --- | --- | --- | --- | --- |
+| `nano-banana-2` | Nano Banana 2 | auto, 21:9, 16:9, 3:2, 4:3, 1:1, 4:5, 3:4, 2:3, 9:16 | 1K, 2K, 4K | model default | up to 8 | yes |
+| `nano-banana-2-lite` | Nano Banana 2 Lite | auto, 21:9, 16:9, 3:2, 4:3, 1:1, 4:5, 3:4, 2:3, 9:16 | 1K, 2K, 4K | model default | up to 8 | yes |
+| `nano-banana-pro` | Nano Banana Pro | auto, 21:9, 16:9, 3:2, 4:3, 1:1, 4:5, 3:4, 2:3, 9:16 | 1K, 2K, 4K | model default | up to 8 | yes |
+| `gpt-image-2` | GPT Image 2 | auto, 16:9, 9:16, 1:1, 4:3, 3:4 | 1K, 2K, 4K | low, medium, high | up to 8 | no |
+| `gpt-image-1.5` | GPT-Image 1.5 | 16:9, 9:16, 1:1 | model default | low, medium, high | no | no |
+| `kling-image-v3` | Kling Image V3 | 21:9, 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3 | 1K, 2K | model default | no | no |
+| `seedream-v4.5` | Seedream 4.5 | 16:9, 9:16, 1:1, 4:3, 3:4 | 2K, 4K | model default | no | yes |
+
+## Video models
+| Model | Name | Seconds | Resolutions | Aspect ratios | First frame | Last frame | Native sound |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `seedance-2.0` | Seedance 2.0 | 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 | 480p, 720p, 1080p, 4k | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | yes | yes | yes |
+| `seedance-2.0-fast` | Seedance 2.0 Fast | 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 | 480p, 720p | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | yes | yes | yes |
+| `seedance-2.0-mini` | Seedance 2.0 Mini | 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 | 480p, 720p | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | yes | yes | yes |
+| `kling-v3-turbo` | Kling 3.0 Turbo | 5, 10 | model default | 16:9, 9:16, 1:1 | yes | no | no |
+| `wan-2.6-flash` | Wan 2.6 Flash | 3, 4, 5 | model default | 16:9, 9:16, 1:1 | required | no | no |
+| `veo-3.1-lite` | Veo 3.1 Lite | 4, 6, 8 | 720p, 1080p | 16:9, 9:16 | yes | yes | yes |
+| `vidu-q3-turbo` | Vidu Q3 Turbo | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 | model default | model default | yes | yes | yes |
+| `wan-2.7` | Wan 2.7 | 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 | 720p, 1080p | model default | required | yes | no |
+
+Veo 3.1 Lite at 1080p is always 8 seconds. With no model named, a video uses `vidu-q3-turbo`; when its `aspectRatio` is one that model cannot make (`9:16` for a vertical clip), it uses the first of `wan-2.6-flash`, `veo-3.1-lite`, `seedance-2.0-mini`, `kling-v3-turbo`, `seedance-2.0-fast`, `seedance-2.0` (cheapest first) that makes that shape with the frames and `duration` given. A model the Block names is kept, and refused if it cannot make the shape. Generated images are stored as measured PNGs (up to 8192 pixels a side); videos are stored as the provider's MP4.
+
+## Music and sound effects
+| Operation | Model | Length | Price |
+| --- | --- | --- | --- |
+| `audio.music` | `ace-step` | 5 to 240 whole seconds (suggested default 30) | The app's music price per started minute |
+| `audio.sfx` | `sound-effects` | 0.5 to 22 seconds in tenths (suggested default 4) | The app's sound-effect price per clip |
+
+## Voices
+`audio.speech` Blocks can suggest any of these voice ids in `settings.voice`. A server offers the voices whose provider it has configured. Price follows the app's Voiceover rate for the text's length.
+
+| Voice id | Name | Provider |
+| --- | --- | --- |
+| `asteria` | Asteria · Clear, confident female | deepgram |
+| `adam` | Adam · Dominant, firm male | elevenlabs |
+| `liam-social` | Liam · Social · Energetic — reels & shorts | elevenlabs |
+| `onyx` | Onyx · Deep, steady male narrator | openai |
+| `nova` | Nova · Bright, clear female narrator | openai |
+| `luna` | Luna · Friendly, youthful female | deepgram |
+| `odysseus` | Odysseus · Calm, smooth, professional male | deepgram |
+| `aurora` | Aurora · Cheerful, expressive female | deepgram |
+| `apollo` | Apollo · Confident, comfortable male | deepgram |
+| `thalia` | Thalia · Confident, energetic female | deepgram |
+| `atlas` | Atlas · Enthusiastic, confident male | deepgram |
+| `hera` | Hera · Warm, professional female | deepgram |
+| `arcas` | Arcas · Natural, smooth male | deepgram |
+| `cora` | Cora · Smooth, melodic female | deepgram |
+| `zeus` | Zeus · Deep, trustworthy male | deepgram |
+| `orion` | Orion · Approachable, calm male | deepgram |
+
+Music, sound effects and catalog voices are stored as the provider's measured MP3 or WAV.

package/docs/reference/limits.md

@@ -0,0 +1,306 @@
+# Limits
+
+Every number below is read from the SDK constant named under its heading, the same value the runtime and StillMade enforce. Exceeding one fails with the error code in the [error reference](errors.md).
+
+## JavaScript Blocks (src/run.js)
+
+`JAVASCRIPT_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Source size | 256 KiB |
+| Input and output JSON | 4 MiB |
+| CPU time per run | 500 ms |
+| Memory | 16 MiB |
+| Sandbox memory reserve | 32 MiB |
+
+## Module Blocks
+
+`MODULE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Files in module/ | 64 |
+| One file | 64 MiB |
+| All files | 128 MiB |
+| File path length | 160 |
+| Run time without progress (host calls do not count) | 2 min |
+| Longest run in real time | 30 min |
+| Extra time after each progress report | 1 min |
+| One message to or from the host | 16 MiB |
+| Log lines kept per run | 500 |
+
+## Standard views
+
+`VIEW_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Markup | 64 KiB |
+| Styles | 32 KiB |
+| Script | 64 KiB |
+| One message to the host | 4 MiB |
+| StillMade.run calls per minute | 30 |
+| Image previews per minute | 60 |
+| One image preview | 15 s |
+| Preview image side (pixels) | 512 |
+
+## Frame views
+
+`FRAME_VIEW_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Markup | 256 KiB |
+| Each stylesheet | 256 KiB |
+| Script bundle (view.js) | 4 MiB |
+| Asset files | 32 |
+| All asset files | 8 MiB |
+| One task before it is stopped | 250 ms |
+| A blocking native operation before the view is closed | 1 s |
+
+## Shared view state
+
+`SHARED_VIEW_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| All shared fields | 384 KiB |
+| One updateShared request | 800,000 bytes |
+| Unsent edits | 2 MiB |
+
+## Hosted operations
+
+`CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Prompt characters | 32,000 |
+| Project context sent with a prompt | 24,000 bytes |
+| System instruction characters | 8,000 |
+| Text output characters | 32,768 |
+| Tokens a reply may use | 4,096 |
+| Fixtures in a capability Block | 3 |
+| Literal phrases one fixture checks | 8 |
+| One literal phrase | 256 |
+| Capability package | 256 KiB |
+| Host metadata | 8 KiB |
+
+## Image generation
+
+`IMAGE_CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Prompt characters | 32,000 |
+| Legacy fixed-size image | 12,000,000 bytes |
+| Legacy fixed width | 1,024 |
+| Legacy fixed height | 1,024 |
+| Longest side (pixels) | 8,192 |
+| Pixels | 40,000,000 |
+| Image file | 64 MiB |
+
+## Video generation
+
+`VIDEO_CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Prompt characters | 32,000 |
+| Video file | 256 MiB |
+| Seconds | 60 |
+| Width (pixels) | 3,840 |
+| Height (pixels) | 3,840 |
+| Pixels per frame | 8,294,400 |
+
+## Speech
+
+`SPEECH_CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Characters per call | 3,800 |
+| Seconds | 1,400 |
+| Audio file | 64 MiB |
+| Canonical WAV sample rate | 24,000 |
+| Canonical WAV channels | 1 |
+
+## Music, sound effects and transcription
+
+`AUDIO_CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Audio file | 128 MiB |
+| Seconds | 1,800 |
+| Music seconds (min, max, default) | min 5; max 240; default 30 |
+| Sound effect seconds (min, max, default) | min 0.5; max 22; default 4 |
+
+## Conversation history (text.generate)
+
+`TEXT_HISTORY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Turns | 20 |
+| Characters per turn | 8,000 |
+| Characters in all turns | 24,000 |
+
+## Web reading
+
+`WEB_CAPABILITY_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| URL length | 2,048 |
+| Instruction characters | 4,000 |
+| Research topic characters | 500 |
+| Sources returned | 12 |
+| Answer characters | 32,768 |
+
+## Media analysis
+
+`MEDIA_ANALYZE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Images per call | 4 |
+| Question characters | 2,000 |
+| Seconds of one closer-inspected video range | 12 |
+
+## Image description
+
+`IMAGE_DESCRIBE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Images per call | 4 |
+
+## Generation from code (media.generate)
+
+`MEDIA_GENERATE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Items per batch | 50 |
+| Prompt characters | 4,000 |
+
+## Generation settings
+
+`GENERATION_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Reference images | 8 |
+| Negative prompt characters | 2,000 |
+| Largest seed | 2,147,483,647 |
+
+## Outside APIs (net.fetch)
+
+`NETWORK_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Declared origins | 8 |
+| Request body | 4 MiB |
+| Response body after decompression | 8 MiB |
+| One request | 30 s |
+| Redirects followed | 3 |
+| Request headers | 32 |
+| All request headers | 16 KiB |
+| URL length | 8,192 |
+| Requests per minute (person and Block) | 120 |
+| Requests per minute to one origin (everyone) | 3,000 |
+| Saved key length | 4,096 |
+
+## Live connections (net.connect)
+
+`SOCKET_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Open connections per run | 4 |
+| One message, either way | 1 MiB |
+| All messages in one run | 256 MiB |
+| Subprotocol names | 8 |
+
+## Cloud storage
+
+`CLOUD_STORAGE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Key length | 200 |
+| One JSON value | 1 MiB |
+| One file | 64 MiB |
+| Everything one Block keeps in a project | 256 MiB |
+| Keys per Block per project | 2,000 |
+| Items per list page | 500 |
+| Media type length | 100 |
+
+## Triggers
+
+`BLOCK_TRIGGER_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Triggers per Block | 4 |
+| Label characters | 120 |
+| Shortest schedule interval (seconds) | 60 |
+| Longest schedule interval (seconds) | 31,536,000 |
+
+## Media transforms
+
+`MEDIA_TRANSFORM_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Ranges kept by one cut | 500 |
+| Videos joined at once | 50 |
+| Media length (seconds) | 21,600 |
+| Decoded samples | 201,326,592 |
+| Decode sample rates | 8,000, 16,000, 22,050, 24,000, 32,000, 44,100, 48,000 |
+| Thumbnail width (pixels) | 4,096 |
+| Joined image side (pixels) | 4,096 |
+| Images in one joined image | 64 |
+| Text pieces in one joined image | 64 |
+| Document pages read | 500 |
+| Document text (characters) | 4,000,000 |
+
+## Files, documents and tables
+
+`DATA_VALUE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| File name length | 255 |
+| Document characters | 1,000,000 |
+| Document title characters | 300 |
+| Table columns | 500 |
+| Table rows | 100,000 |
+| Table cells | 500,000 |
+| Column name length | 160 |
+| Characters in one cell | 100,000 |
+| Link length | 8,192 |
+
+## File bundles
+
+`FILE_BUNDLE_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Files | 256 |
+| Text in all files | 3,000,000 bytes |
+| Path length | 180 |
+
+## JSON schemas (text.generate)
+
+`JSON_SCHEMA_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Schema size | 8 KiB |
+| Nesting depth | 8 |
+| Properties per object | 64 |
+| Values per enum | 64 |
+| Characters in a schema string | 4,000 |

package/docs/reference/manifest-kinds-controls.md

@@ -0,0 +1,36 @@
+# Kinds and generated controls
+
+## Kinds
+| Kind | Behaviour |
+| --- | --- |
+| `task` | A Project Type Step. Its primary input and output connect automatically to neighbouring Steps. Use this for almost every Block. |
+| `workspace` | A complete project workspace that owns a project document (like Shots or the Editor). Never connected automatically: neighbours only reach it through project context or explicit connections. |
+| `editor-extension` | Accepted by the validator; no host behaviour depends on it today. Use `task`. |
+
+## Generated controls
+`manifest.ui` binds generated controls to inputs. A custom view replaces them in the interface, but keep them as the fallback schema.
+
+| Control | Use |
+| --- | --- |
+| `text` | Single- or multi-line text for a `text`-like input. |
+| `number` | A number field for `number`/`integer` inputs. |
+| `slider` | A range slider for a bounded number input. |
+| `checkbox` | A toggle for a `boolean` input. |
+| `asset` | A media picker for `image`, `video`, `audio` or `asset` inputs. |
+| `select` | One choice from a list. |
+| `multiselect` | Several choices from a list. |
+| `file` | An upload for a `file` or `file[]` input: PDF, TXT, CSV, Markdown, JSON or ZIP, checked by type and bytes before the Block sees a saved reference. |
+| `date` | A date picker for a `date` input; add `time: true` for a date and time. |
+| `color` | A color picker with a hex field for a `color` input. |
+| `url` | A web address field for a `url` input (http or https). |
+| `richtext` | A Markdown editor with a preview for a `document` input, or a `text` input written in Markdown. |
+| `list` | An item-by-item editor for `text[]`, `number[]`, `integer[]`, `url[]`, `date[]` or `color[]` inputs. |
+| `grid` | A grid editor for a `table` input, with add and remove rows and columns and CSV paste. |
+| `gallery` | Presents an `image[]` output as a gallery. |
+| `before-after` | Compares an `image` output with a declared `image` input. |
+| `table` | Presents a `table` output as a paged table with a CSV download. |
+| `document` | Presents a `document` or Markdown `text` output as formatted text. |
+| `chart` | Draws a `table` (optional `x` and `y` column names) or `number[]` output as a `bar` or `line` chart (`chart`). |
+| `code` | Presents a `text`, `json` or `object` output as code with a copy button (optional `language`). |
+| `player` | Plays an `audio` or `video` output (or a list of them); a video plays in StillMade's player, with full screen. |
+| `download` | Offers a `file`, `file[]` or `file-bundle` output as a download through the host export policy. |

package/docs/reference/manifest.md

@@ -0,0 +1,181 @@
+# Block manifest
+
+## Package envelope
+Recipe packages contain `manifest`, `recipe`, and `tests`. JavaScript packages contain `manifest`, `code`, and `tests`. Unknown envelope and manifest fields are rejected.
+
+## Manifest example
+```json
+{
+  "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.word-count",
+  "action": {
+    "label": "Count words",
+    "running": "Counting words…"
+  },
+  "version": "1.0.0",
+  "name": "Word count",
+  "description": "Counts words and returns trimmed text using isolated JavaScript.",
+  "kind": "task",
+  "runtime": "javascript",
+  "inputs": {
+    "text": {
+      "type": "text",
+      "semantic": "plain_text",
+      "required": true,
+      "description": "Text whose surrounding whitespace should be removed."
+    }
+  },
+  "outputs": {
+    "text": {
+      "type": "text",
+      "semantic": "plain_text",
+      "description": "The trimmed source text."
+    },
+    "words": {
+      "type": "integer",
+      "semantic": "word_count",
+      "description": "The number of whitespace-separated words."
+    }
+  },
+  "permissions": {
+    "project": [],
+    "network": [],
+    "filesystem": [],
+    "secrets": []
+  },
+  "ui": [
+    {
+      "control": "text",
+      "port": "text"
+    }
+  ]
+}
+```
+
+## Required fields
+| Field | Contract |
+| --- | --- |
+| schemaVersion | Integer 1 |
+| sdkVersion | Exact stable version 0.1.0, caret, tilde, or comparator intersection satisfied by this host |
+| id | Lowercase namespace.name; sm. is reserved |
+| version | Three-part SemVer, such as 1.0.0 |
+| name | 1–120 characters |
+| description | 1–1000 characters describing behavior |
+| kind | task, workspace, editor-extension, or composite |
+| runtime | recipe, javascript, reviewed capability, or reviewed comfyui adapter |
+| inputs / outputs | Named port objects; at most 64 in each direction |
+| permissions | Explicit supported permission families |
+
+## SDK compatibility
+The runtime remains SDK `0.1.0`; exact declarations remain valid. A Block may also declare a bounded stable range such as `^0.1.0`, `~0.1.0`, or `>=0.1.0 <0.2.0`. `sdkCompatibility(declared)` reports `supported`, `unsupported` or `invalid` against that actual runtime version. `validateManifest` enforces the same result. A supported range never bypasses permissions, runtime availability, source admission or fixtures.
+
+Supported grammar is an exact stable three-part version, caret, tilde, or up to four space-separated comparator intersections (`=`, `>`, `>=`, `<`, `<=`). Numeric components are bounded to 999999. Tags, prereleases, wildcards, alternatives and hyphen ranges are unsupported. Major-zero caret rules apply: `^0.1.0` excludes `0.2.0`; `^0.0.3` excludes `0.0.4`. A declaration is preserved verbatim in its package identity; changing it requires a new immutable release. Do not widen it merely to silence an incompatibility.
+
+This is compatibility checking, not automatic code adaptation or a promise of future SDK support. Explicit reviewed Step-state migration routes are documented separately; changing an SDK range never runs a migration or changes project pins.
+
+## Port fields
+| Field | Meaning |
+| --- | --- |
+| type | A supported type, optionally followed by [] |
+| required | Defaults to required; set false for omission |
+| default | Used when no value is supplied; must match the type |
+| min / max | Inclusive numeric bounds |
+| primary | At most one true per direction |
+| role | Lowercase semantic identifier such as source_image |
+| context | A supported input-only context field with matching type and permission |
+| description | Help text explaining the port |
+
+## Optional metadata
+`ui` binds controls to inputs. `license` records source licensing. `provenance` records remix or adaptation origin. `summary` records the source-linked description. `category` groups related capabilities. `entry` is descriptive metadata; execution uses the packed source.
+
+## Platform compatibility
+Block cards and listing pages show Phone, Browser, and Desktop SVG indicators.
+Phone means a phone browser; Browser means a desktop web browser; Desktop means
+the downloaded StillMade app. Add optional `manifest.platforms` to declare all
+three environments. Each entry has `supported` (boolean) and an optional `reason`
+(up to 240 characters); unsupported environments require a reason. At least one
+environment must be supported. For example, a Block with a desktop-only interface:
+
+```json
+{
+  "platforms": {
+    "phone": {"supported": false, "reason": "This interface requires the StillMade desktop app."},
+    "browser": {"supported": false, "reason": "This interface requires the StillMade desktop app."},
+    "desktop": {"supported": true}
+  }
+}
+```
+
+A declaration is a request to support a platform, **not verification**. An
+unsupported declaration keeps that platform unavailable. `supported:true` or an
+omitted declaration never lights an icon on its own. Runtime portability does not
+prove usable UI. Unknown, stale, or missing checks display **Not verified**.
+
+StillMade's server-owned import and release review runs `testPlatforms` against
+the actual working preview, using the same isolated runtime and UI frame as the
+app. Reports are stored with the existing import/release report and bound to the
+exact source digest. Package-supplied reports are rejected. Changing code, UI,
+fixtures, or compatibility metadata invalidates the previous source report.
+Built-in audits also track the production UI source fingerprint.
+
+The current `mobile-ui-1` gate checks 320 × 720, 390 × 844, 768 × 1024,
+844 × 390 phone landscape, and 1280 × 800 desktop containers in Light, Dark,
+and White. It uses the real embedded Block/Project Type host and custom sandbox,
+then checks the main touch task, empty/populated/loading/error/success states,
+long labels, enlarged text, and continuity through resize, rotation and panel
+toggles. Ordinary touch controls target 44 × 44 CSS pixels. Fields require
+accessible labels; draggable actions require a visible tap or menu alternative.
+Intentional canvas/timeline panning remains distinct from page-wide overflow.
+See [Mobile-compatible Block UI](../build/mobile-ui.md) for authoring patterns.
+
+For a custom interface with multiple buttons, put
+`data-stillmade-action="run"` on the button that runs the included sample through
+`StillMade.run`. The test clicks that control inside the disposable sandbox;
+no generation provider, account API, or device permission can be invoked there.
+A single-button interface can use its sole button. Interfaces requiring more
+complex interaction remain unverified until their host adapter covers it.
+
+The SDK exports `testPlatforms`, `measurePlatformLayout`,
+`assessPlatformCapture`, and `checkedPlatformTargets`. A trusted browser adapter
+renders the real interface, calls `measurePlatformLayout` in every frame, tries
+its interaction, and returns frames plus interaction, embedding, state, and
+continuity evidence. Use the checker in
+an external test harness as follows:
+
+```js
+const fixtures = await testPackage(pkg);
+const devices = await testPlatforms(pkg, {
+  runtimePassed: fixtures.passed,
+  probe: trustedBrowserAdapter,
+});
+```
+
+`admitPackage` accepts the same adapter as `platformProbe` and includes
+`platformChecks` in its result. Without a browser adapter it reports unverified
+platforms; CLI `validate --mobile` exposes the exact required profile but remains
+pending until a trusted embedded browser run, and code-only fixture tests never claim device support.
+In StillMade, use **Run mobile UI profile** in import review to inspect the
+server's result. Import confirmation repeats the server-owned checks.
+
+Cloud-side checks cover Phone and Browser. They do not masquerade as an Electron
+check: Desktop stays unverified without an actual desktop-runner report. The
+built-in audit runner tests the Electron renderer separately. Browser emulation
+is not a physical iOS-device test, and macOS Electron does not certify a Windows
+installer or native recording capability. Cloud/ComfyUI operations still require
+their normal configured connection; checks never make a paid sample call.
+
+Project Types combine enabled, version-pinned Blocks. An unavailable dependency
+makes that platform unavailable; an unverified dependency keeps it unverified.
+These indicators do not grant filesystem, process, system recording, or other
+native permissions. Unsupported native APIs still fail admission/runtime checks.
+
+## UI schema
+Use an array of `{control, port}` objects. Controls are `text`, `number`, `slider`, `checkbox`, `asset`, `select`, `multiselect`, `file`, `date`, `color`, `url`, `richtext`, `list`, `grid` (the list StillMade validates). Every control binds to a declared input. A `text` control is a box that grows with its lines; add `"multiline": true` for anything typed one item per line or as a list (`{"control":"text","port":"listingFacts","multiline":true}`), so no host draws it as one line. Image, video, audio and file inputs, and their lists, take `asset`; a picture list shows photo tiles. The host renders these fallback controls in StillMade’s style. A separate package-level `view` may supply a [sandboxed custom interface](../build/custom-interface.md); it never loads into the parent app DOM.
+
+## Permissions
+Supported families are `project`, `network`, `filesystem`, `secrets`, and `capabilities`. Network, filesystem, and secrets arrays must be empty. A capability runtime declares exactly one supported operation: `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`; reviewed ComfyUI declares `comfyui.execute`. These permissions do not grant JavaScript or a custom interface direct host access. Supported context read permissions are listed in [project context](../build/context.md).

package/docs/reference/operations.md

@@ -0,0 +1,36 @@
+# Recipe operation reference
+
+## value.copy
+Copy a JSON value without changing it.
+
+Arguments: `value`.
+
+Values are resolved from input bindings or completed earlier recipe operations.
+
+## text.trim
+Remove leading and trailing whitespace.
+
+Arguments: `text`.
+
+Values are resolved from input bindings or completed earlier recipe operations.
+
+## text.replace
+Replace literal text; no regular expressions.
+
+Arguments: `text`, `find`, `replacement`.
+
+The find value is literal text, not a regular expression.
+
+## text.join
+Join an array of text values.
+
+Arguments: `items`, `separator`.
+
+items must be an array of strings. separator controls the text between items.
+
+## image.thicken-lines
+Expand dark outlines while preserving other colors.
+
+Arguments: `image`, `thickness`, `threshold`.
+
+Accepts decoded RGBA. Thickness is an integer from 1 to 8; threshold is from 0 to 255. Defaults are 2 and 100. Dark outlines expand with a square neighborhood; unrelated colors remain unchanged.