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.

{
  "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.

{
  "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:

{
  "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:

{"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.