# 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](/docs/reference/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](/docs/reference/browser-applications)
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`:

```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

1. Establish an upstream baseline with a representative input and inspect the
   exported bytes. Retain the original app's important behavior and interface.
2. 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.
3. Execute a real producer → imported application → consumer through the
   production resolver. Fixtures, screenshots, schemas and successful process
   exit codes alone cannot prove transformed output.
4. Decode exports; compare with the baseline; verify the consumer receives those
   exact bytes. Check real playback separately from codec decoding.
5. 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.
6. 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.