GitHub application imports
Inspect repository applications, preserve their interfaces and use supported execution contracts.
Import an application from GitHub
This guide describes the current SDK boundaries and the integration procedure. It does not claim that every repository can already run inside StillMade. The source contract, import inspector, restricted UI and reviewed native adapter are implemented. An isolated application build worker and bundled React/Vue/Svelte runtime are still required for arbitrary web applications.
Preserve the requested scope
The default GitHub import intent is the complete application with its existing interface. Record the immutable commit, application root and important actions before adapting code. The importer must not replace that intent with one utility. The separate Extract one capability mode explicitly authorizes narrower scope.
The in-app full-application inspection pins source and retains an inventory of code, binary assets, dependency manifests, lockfiles, symlinks and submodules. It returns not-built, including unfinished feature and runtime checks. A complete file inventory is neither a complete dependency checkout nor a successful build. Inspection uses public unauthenticated GitHub APIs; it does not authorize private repository access, install dependencies, execute scripts or charge model credits.
Use the exported defineRepositoryApplication contract to record the requested scope, interface, versioned route and source-backed feature ledger. Use assessRepositoryApplication to identify missing evidence. Its highest status is evidence-complete: supplied receipt declarations are not independent execution verification. The assessor always reports executionPerformed:false and independentlyVerified:false. A model cannot certify its own integration by filling in that object.
Choose an actual runtime
| Source | Current boundary |
|---|---|
| Existing SDK source folder/package | Import its pinned source and run normal admission. |
| Bounded JS or recipe capability | Adapt the real computation to the existing sandbox and provide typed contracts. This is capability scope. |
| Restricted HTML/JS custom view | Supported within the documented DOM and bridge restrictions. Original styling may be preserved. |
| React, Vue, Svelte, workers, arbitrary WASM or full frontend bundle | No general application runtime yet. Do not paste a bundle into view.javascript, remove security checks, or claim a static mount as acceptance. |
| Natron native application | An approved desktop adapter retains the original application in a separate native window and performs bounded rendering. It is not embedded web UI or a source build. See Desktop execution. |
| Arbitrary native executable, Python/Node backend or full stack service | Requires an implemented, reviewed isolated runtime and capability contract. A README, wrapper or external command is insufficient. |
The separate experimental browser application contract preserves compiled assets and original UI code with a Block-owned lifecycle adapter. The exact reviewed Method Draw source has a private desktop install, editing and SVG export path. Other applications require separate source, runtime and result review; package validation alone is insufficient.
Keep the original appearance
For an eligible restricted view, place this option in src/view.json:
{"appearance":"original"}Keep the application's permitted CSS in src/view.css. StillMade still supplies the outer workspace, focus and permission controls. Original appearance does not grant extra scripting, networking, storage or navigation permissions.
To offer optional StillMade styling, include src/view.themed.css using the documented theme tokens. The themed preview is offered only when that stylesheet passes appearance checks. Omitted appearance preserves the existing package behavior; published packages are not rewritten to change this preference.
Connect meaningful inputs and outputs
Every required input needs a physical type, a precise semantic meaning, allowed sources, and an explicit way to supply missing data. Do the same for output meaning and representation. A video output is the actual new saved video, with its own exact asset/version identity; returning the source video is not evidence that an editor transformed it.
The existing image type also accepts bounded inline RGBA pixels as {width, height, data}. A small editor can import those pixels and return its actual composited pixels without inventing an asset ID. Respect both the image contract and the complete runtime message limits. Large or referenced media still needs the host's authenticated asset resolution and materialization path; a guest-local data/blob URL is not a durable shared asset.
Map existing app behavior to SDK input, shared-document and output interfaces. Do not recreate the application's logic in the shared host or add a special Block-ID branch. Persist editable state through declared host services and keep two placements separate. Input changes, revoked permission, cancellation and closed workspaces must reject late completion.
Native output-producing actions use src/desktop.json: declarative mappings from typed input ports into an approved adapter and from its actual result into output ports. The trusted host produces a receipt bound to the package, invocation, inputs and outputs. Neither a Block's view nor its JavaScript can supply the host executor or mint accepted native evidence. Legacy native packages without this mapping cannot pass a generic workflow by returning their input unchanged.
Prove the integration
- Establish an upstream baseline with a representative input and inspect the
exported bytes. Retain the original app's important behavior and interface.
- Build only in a disposable isolated worker without application credentials,
customer mounts or unrestricted network access. Preserve licenses and exact dependency/asset identities. If no suitable worker exists, report that gap.
- Execute a real producer → imported application → consumer through the
production resolver. Fixtures, screenshots, schemas and successful process exit codes alone cannot prove transformed output.
- Decode exports; compare with the baseline; verify the consumer receives those
exact bytes. Check real playback separately from codec decoding.
- Save/reopen, edit while running, cancel, revoke access, retry failures, use two
placements and verify stale output behavior. Exercise permission and resource limits with hostile inputs.
- Retain the tested package digest, source commit, runtime version, commands,
bounded logs, artifacts and pass/fail evidence. Install the exact artifact tested. Edits require new checks and published contract changes need a new version.
Keep inspection, source admission, runtime tests and production verification as separate states. Native bindings validate host-issued evidence; they are not a cryptographic attestation from an arbitrary caller. The trusted host is responsible for process isolation and actual artifact verification.
The first local Natron acceptance rendered 24 frames of an inverted synthetic video, passed the real result through a three-Step workflow, matched its decoded pixels exactly to an independent native baseline, and reopened saved workflow and media. The same H.264/YUV420 output also played all 24 frames in a sandboxed Electron video element. ProRes decoded successfully in the native probe but did not play in Chromium; choose a browser-compatible Writer codec or explicitly produce a separate playback proxy. This establishes that specific macOS software-rendering path. It does not establish all Natron features, third-party plugins, original GUI containment, product UI media routing, other operating systems, source build reproducibility, or arbitrary-repository support. The repository acceptance harness and evidence remain distinct from the SDK's offline tests.