Building documents

Rules that most often trip people up

Mistake	Code	Fix
mimetype compressed, not first, or with a trailing newline	IDOP-PROFILE-001, -002	Add it first with zip -X -0 and no newline
Directory entries in the ZIP	IDOP-ZIP-032	Pack with zip -D
Inline <script>…</script>	IDOP-POLICY-014	Move code to a .js file under code/
onclick= and other inline handlers	not refused, but never run — the sandbox’s content security policy blocks them	Use addEventListener in a script file
A script, font or image from a remote URL in HTML	IDOP-POLICY-011	Put the file in code/ or resources/
A remote URL or @import in CSS	IDOP-POLICY-012	Bundle the file in the package
fetch()	sandbox blocks it	Declare a capability and use idop.network.request
A .js file under resources/	IDOP-POLICY-001	Only code/ may contain code

Behave well

• Write to storage promptly. Users can only save what is in storage.
• Handle a first run. IDOP-STORAGE-NOT-FOUND on first open is normal.
• Version your data. Use state.schemaVersion and migrate old data when you change its shape.
• Ask for the least. Prefer optional capabilities, and state a purpose a person can understand.
• Show example content honestly. If you ship sample data, let the user clear it.

Accessibility

Documents are web pages, and the usual practices apply: semantic HTML, labelled controls, keyboard operation, sufficient contrast, and respect for prefers-reduced-motion. See §19 of the specification.

With AI

Give a model the authoring prompt and describe the document you want. Validate the result before sharing it.