Authoring contracts
Build Design and Video templates that preserve editable structure, pass the current importer rules, and become safe session-owned copies.
An iPolloWork template is a reproducible starting point, not a screenshot or a stored chat response. The package must tell the importer what it contains, tell the chosen editor what it may safely edit, and remain self-contained when it becomes a new session-owned project.
The importer validates the package, the editor uses the declared surface and variables, and a session materializes its own copy.
What a creator maintains
HTML, CSS, JavaScript, and local assets live in version control with relative paths.
Names identity, version, category, surface, entry, license, and editing contract.
What the importer accepts
A ZIP archive with `manifest.json` at its root and no unsafe paths or executable payloads.
Checks schema, category/surface/entry compatibility, size limits, and allowed file types.
What a person actually edits
Using a template materializes an independent session-owned project.
The session record aligns sidebar, editor, and agent instructions with the same template identity.
Choose the correct editing surface
| Template kind | Manifest values | Entry contract | Editor-facing contract |
|---|---|---|---|
| Website, app, deck, poster, card, report, or article | a design category and surface: "design" | static entry.html by convention | semantic HTML, CSS tokens, stable selectors, relative assets |
| HyperFrames video | category: "video" and surface: "video" | index.html at archive root | valid composition structure plus data-composition-variables |
The current v1 manifest keeps kind: "design" for both classes; surface selects the editor. A video package must use the video category, video surface, and root index.html together. The importer rejects mismatched combinations because a Design project and a HyperFrames composition have different runtime contracts.
Author Design templates as structured documents
Design templates are ordinary editable web projects. Use a self-contained HTML entry, semantic landmarks, stable IDs where an agent or editor needs them, responsive CSS, and tokenized values that make change safe. A template with a flattened image of a layout is not an editable Design source.
A good template exposes a small, named change surface while preserving the underlying document structure.
- 01Structure
Use semantic HTML for the page, sections, data areas, and reusable components.
- 02Tokenize
Keep reusable visual values in a declared token stylesheet, preferably with `--ipw-*` custom properties.
- 03Expose
Declare `designSystem.variables` for supported editing controls and group them by the intended user decision.
- 04Validate
Open a new session copy and test both a normal-size and a narrow layout after making edits.
Example authoring conventions:
<link rel="stylesheet" href="design-tokens.css" />
<h1 data-ipw-text="hero.title">Make the signal visible.</h1>
<article data-ipw-card>...</article>
The attributes are conventions that make authoring tools and agents easier to target; the essential requirement is a real, structured, editable project. A 16:9 SVG or PNG cover is recommended for a clear Template Market card.
Author Video templates as one isolated composition
Video templates are HyperFrames projects. The active project belongs at the session's video/<session-id>/index.html; a Video template must keep its playable index.html at the package root so the materializer can create that session-owned project. Do not start a second preview server inside the template—the embedded preview is owned by iPolloWork.
<html data-composition-variables='[
{"id":"title","type":"string","label":"Title","default":"Product Reveal"},
{"id":"accent","type":"color","label":"Accent","default":"#3a9fca"}
]'>
<body>
<div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
<section id="scene-main" class="clip" data-start="0" data-duration="6" data-track-index="1" style="color: var(--accent)">
<h1 id="title" data-var-text="title">Product Reveal</h1>
</section>
</div>
</body>
</html>
Each declared video variable needs an id, type, label, and default; an enum also needs options. Scalars become CSS variables on the composition root, while data-var-text and data-var-src provide direct bindings. Before import, run the same structural check used by built-in video templates:
npx --yes hyperframes@0.7.52 check . --strict --at-transitions
Package defensively
The importer accepts static HTML, CSS, JavaScript, JSON, image, font, text, Markdown, LICENSE, and NOTICE files. It rejects symbolic links, executable files, absolute paths, .. traversal, and duplicate paths. The present limits are 50 MB for the archive, 200 MB after extraction, 1,000 files, and 25 MB per file.
Use lowercase semantic IDs such as acme.growth-brief; local packages cannot use the reserved ipollowork.* namespace. Keep semantic versioning meaningful: update the version for an evolved package and choose a new ID for a genuinely distinct template.
A release check that catches the real failures
- Build from a clean source directory with only relative asset references.
- Inspect the archive root:
manifest.jsonmust not be nested under another folder. - Confirm category, surface, and entry are compatible.
- Import the
.ipwtinto Template Market and select Use. - Verify the newly created session rather than the library entry.
- For Design, change every declared editable group and check a narrow viewport.
- For Video, run HyperFrames validation, preview the whole duration, and exercise each declared variable.
- Keep the source in version control; treat
.ipwtas a distribution artifact only.
Read Package format for the concrete manifest and archive structure, then follow Design template or Video template.