# Hosted timeline proposals

Create a reviewed structured-editing Block that preserves project media and applies only after confirmation.

# Hosted timeline proposals

Use `timeline.propose` when a Block needs an LLM to choose reviewable edits from the current timeline. The Block declares the editing policy and typed context. StillMade owns the provider connection, model selection, payment review, exact execution receipt, output validation, preview, and Apply action.

This capability never gives package code access to project storage, provider credentials, or an unrestricted editor API. Its only accepted output is the public `timeline-edit` schema. The host compares each command's `before` value with the current project before applying it through ordinary permissions and undo history.

## Manifest

The manifest must use runtime `capability`, entry `src/capability.json`, exactly one `timeline-edit` output, and one to four inputs. At least one input must be a `timeline`. A project-bound timeline input declares `context: "timeline"`. The Block must declare both `context.timeline.read` and `timeline.propose`, plus the single capability permission `timeline.propose`.

```json
{
  "runtime": "capability",
  "entry": "src/capability.json",
  "inputs": {
    "timeline": {"type":"timeline","context":"timeline","primary":true},
    "direction": {"type":"text","default":"Polish this cut conservatively."}
  },
  "outputs": {"edit":{"type":"timeline-edit","primary":true}},
  "permissions": {
    "project":["context.timeline.read","timeline.propose"],
    "capabilities":["timeline.propose"],
    "network":[],"filesystem":[],"secrets":[]
  }
}
```

## Capability descriptor

`src/capability.json` contains exactly `schemaVersion`, `operation`, `context`, `instruction`, `maxTokens`, and `output`.

```json
{
  "schemaVersion": 1,
  "operation": "timeline.propose",
  "context": {
    "timeline": {"$input":"timeline"},
    "direction": {"$input":"direction"}
  },
  "instruction": "Use exact before snapshots, preserve locked items, and return strict JSON only.",
  "maxTokens": 2000,
  "output": "edit"
}
```

`context` must bind every declared input exactly once. Instructions contain 1–6,000 characters. `maxTokens` is 1–4,096. Bound context is inert JSON and must stay under 24,000 encoded bytes so the exact reviewed request remains bounded.

The provider must return one strict JSON object with the public timeline-edit shape:

```json
{
  "schemaVersion": 1,
  "title": "Polish the cut",
  "timelineId": "timeline-1",
  "commands": [
    {
      "collection": "clips",
      "operation": "transition",
      "before": {"id":"clip-1","trackId":"video","start":0,"duration":4},
      "values": {"type":"Cross dissolve","duration":0.35,"soundOn":false,"soundId":""}
    }
  ]
}
```

Supported commands and their exact value fields are defined by `packages/block-sdk/timeline-edits.js`. Outputs with prose, code fences, unknown fields, unsupported commands, duplicate targets, more than 100 commands, invalid timing, or malformed `before` values fail before preview or Apply.

Fixtures use nondeterministic expectations:

```json
{"edit":{"kind":"timeline-edit","minCommands":1,"maxCommands":10}}
```

Offline validation checks the contract, source, permissions, interface, fixtures, and remix readiness. It reports live execution as review-required. In StillMade, import and execution require the normal model/payment review. A generated proposal is shown to the user and never changes the timeline until Apply.