# Protocol and Step Module Packages

The verified importer is `parseProtocolPackage` in Listen Step `www/core.js`, and the file importer is `importProtocolFile` in `www/app.js`. The format is `listen-step-protocol@1`. Save UTF-8 JSON as `<name>.listenstep.json`.

Minimal protocol:

```json
{
  "format": "listen-step-protocol@1",
  "name": "Example protocol",
  "tags": ["Example"],
  "steps": [
    {"order": 1, "action": "Prepare the sample"},
    {"order": 2, "action": "Incubate the sample", "timing": "5 minutes"}
  ],
  "materials": [{"name": "Tube", "vendor": "", "catalog": "", "price": "", "currency": "", "url": ""}]
}
```

- Steps are objects, with numeric `order` and nonempty `action`. Use unique ascending order values. The importer sorts by `order` and appends `timing` in parentheses. Use English duration phrases where the built-in timer should recognize them; verify any specific duration against the target app.
- `tags` and `creators` are optional arrays of strings. Top-level `source`, `authors`, and `sources` may carry attribution, but do not invent it. The importer ignores arbitrary step-level metadata; do not rely on it being retained.
- Materials use top-level objects. The importer preserves `name`, `vendor`, `catalog`, `price`, `currency`, and `url`, but does not preserve an input `detail` field. Put necessary experimental details in steps; avoid pretending that arbitrary material fields survive.
- A protocol step may contain `table: {"name":"...","header":[...],"rows":[[...]]}`. The importer attaches this table after the step. Normal protocols must have at least one step; standalone top-level tables are a Step-module feature.
- For a Step module set `"kind":"module"`. Its top-level `tables` is an array of `{name, afterStep, header, rows}`; `afterStep: 0` is before the first step. A module can contain only tables if at least one is nonempty. Import from the module import action, or let the importer honor `kind: module`.
- Explicit alternative steps belong in a module: use contiguous steps with the same `branchGroup` string, or a step object with at least two nonempty `alternatives` (strings or `{action,timing}` objects). Do not infer alternatives from natural-language "or". Actual branch selection occurs when the module is used in a protocol.
- Sample/Recipe attachments use the app's `labItems` snapshot schema and are validated by the app. Do not synthesize that complex schema without an actual exported example and app validation. For standalone Sample/Recipe imports in version 2.63.0 or later, see [lab-module-format.md](lab-module-format.md).
- The validator is conservative and cannot guarantee that every optional app-specific property will survive. Confirm target app version and inspect the imported result, especially tables, branches and attachments.

Deliver the JSON file; the user can select the app's import action or open/share the attachment with Listen Step. A browser workspace import uses that workspace's currently selected account. Existing protocols store inserted module content as snapshots, not live links.
