Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 60 additions & 9 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ already holds text to the content check's rules, from the pack an untrusted chec
`apps/skills` plays every example untrusted too. Measured on a five-question quiz, at four
characters a token: `content.json` was about 3,470 tokens to write by hand, after reading 3,900 to
9,500 of a type's semantics; the source is 1,000 to 1,800 tokens, written from a type file of 200
to 3,000. Twenty-eight things the code does not say by itself:
to 3,000. Twenty-nine things the code does not say by itself:

- **One generator, three ways to run it.** The third, `saved`, checks content as H5P stores it
(*Saved content is checked as the build checks what it writes*, below). `ContentGenerator` was the sweep's
Expand Down Expand Up @@ -290,10 +290,11 @@ to 3,000. Twenty-eight things the code does not say by itself:
the author package pins, so the page plays with the pack it built from. A chat with no tool to
run at all, as ChatGPT on a free account once its data-analysis quota is spent (for hours, the
owner's test of 2026-11-09), cannot write the link: the skill has it put the whole source in its
reply, since that test's chat gave the page's bare address, which builds nothing. Since
2026-11-14 a chat writes a page that makes the link, with or without a tool (*In a chat that
built nothing, a page the chat writes makes the link*, below), and a source goes over in a
`json` block only where it names files.
reply, since that test's chat gave the page's bare address, which builds nothing. From
2026-11-14 a chat wrote a page that made the link (*In a chat that built nothing, a page the chat
writes makes the link*, below), and a source went over in a `json` block only where it named
files. Since 2026-11-15 it writes the link itself, the source in it as JSON, for a source that
names files too (*In route 4 the model writes the link, the source in it as JSON*, below).
A link is only what a command printed (2026-11-11). A link ChatGPT gave the owner carried 3,167
characters that were no deflate stream, its table broken at byte 82 of 2,375: the chat had
typed them itself, made up or copied wrong, and the page built nothing. So the skill says it
Expand All @@ -302,6 +303,9 @@ to 3,000. Twenty-eight things the code does not say by itself:
block and no link under the old text and the new (12 replies, half of them asked for a link to
click), so the rule costs that position nothing, and what it changes in ChatGPT is not
measured. No rule reaches a link copied wrong between the command's output and the reply.
This holds for the compressed link of routes 1 to 3. Since 2026-11-15 route 4's link carries
the source as readable JSON, which the model writes as its own text and the build page reads
leniently (*In route 4 the model writes the link, the source in it as JSON*, below).
An install that hangs is one that fails (2026-11-13): ChatGPT, asked why it had built nothing,
said its `npx` had timed out, and step 3's list named only errors. Haiku in a terminal whose
registry took each connection and never answered went on to the two files under the old text
Expand Down Expand Up @@ -783,7 +787,9 @@ to 3,000. Twenty-eight things the code does not say by itself:
2: built from the archive, made one connection to the registry, and handed the package over
unverified, with its files and the link its command printed. With npm working, 1 of 1 ran the
verifier as before and handed over its pass.
- **In a chat that built nothing, a page the chat writes makes the link** (2026-11-14, #202). The
- **In a chat that built nothing, a page the chat writes makes the link** (2026-11-14, #202;
replaced on 2026-11-15 by *In route 4 the model writes the link, the source in it as JSON*,
below). The
link to the build page was the weak point of a chat that cannot build: compressed text that a
command prints and the model copies into its reply. ChatGPT broke 2 of 3 on 2026-11-13 (*The
hand-over carries the source and one web address*, above), and with its code tool unavailable, as
Expand Down Expand Up @@ -890,9 +896,11 @@ to 3,000. Twenty-eight things the code does not say by itself:
`two-files.md`), anything else (route 4, `browser.md`). Routes 1 to 3 hand over by
`built-here.md`: the build's problems and the file's name, the verifier, run only where npm
answered, the link, written in the verifier's command line, and the hand-over.
- Route 4 writes the page; outside a chat, it writes the page to an `.html` file, which makes the
link from a `file:` address as well, where it used to give a link a command printed, so that the
link's commands are written once, in `built-here.md`.
- Route 4 runs no link command: the link's commands are written once, in `built-here.md`. It
wrote the page, and outside a chat the page to an `.html` file, until 2026-11-15. It now hands
over a link the model writes, and outside a chat also saves the source as `.source.json`, which
the build page opens under *Or open a file* (*In route 4 the model writes the link, the source
in it as JSON*, below).

What a chat reads of the skill's own text, `SKILL.md` and its route's files: 9.8 KB in the
user's browser, 11.3 with npm, 11.5 from the archive and 12.0 from two files, where every route
Expand Down Expand Up @@ -925,6 +933,49 @@ to 3,000. Twenty-eight things the code does not say by itself:
- A run called the Skill tool and got the skill installed on this computer, an older text: the
lab's prompts now say the reader is the skill. Haiku also read a route's file before its check
now and then, at most 1.5 KB more.
- **In route 4 the model writes the link, the source in it as JSON** (2026-11-15, #206, the
owner's call: "i dont want a code snippet at all here"). The page of *In a chat that built
nothing, a page the chat writes makes the link*, above, worked in ChatGPT on a free account (the
owner, 2026-11-15), but the person saw a block of HTML, opened it with Preview, waited, and clicked
a small link. A model cannot compress a source, but it writes its own JSON, so the build page
reads `#source={…}` too (missing-elements.github.io#54), and route 4 is one Markdown link the model
writes: the source on one line, eight characters escaped (space, `%`, `&`, `\`, `(`, `)`, `<`,
`>`), the rest as it is, letters of any language too. No code block, no command, no Preview. A
source that names files gets the link too, since the page asks for the files before it builds.
Outside a chat the source also goes to a `.source.json` file, since a terminal may not open such
a link. Routes 1 to 3 keep the compressed link their command prints.

The page reads the readable form leniently, because a weak model's JSON slips (the owner found a
free account's Gemini 3.5 Flash-Lite poor at plain JSON). Each run of escapes is decoded where it
is UTF-8, a bare `%` is kept, a link run on into its sentence is read up to its last `}`, up to
three braces or brackets left open at the end are closed, and text that is still no JSON goes in
the box with where it breaks, for the chat to fix. Only a compressed link that cannot be read is
called damaged. Eleven kinds of link, rendered by markdown-it as a chat renders one and opened in
Chromium, Firefox and WebKit: 33 of 33 as expected.

Measured on Haiku with a logging skill reader: each reply rendered by markdown-it, its link read
by Node's URL as a browser reads it, decoded as the page decodes it, built, and verified.

- **Seven escapes, the reply's parts in prose:** 5 of 7 built and passed: Question Sets in
English and Ukrainian, a Drag the Words with `%` and parentheses, a three-chapter Interactive
Book, and a Question Set from a code tool with no network. A True/False left one closing `}`
out. An Accordion on HTML tags wrote `&lt;`, which Markdown turns into `<`, a raw `\`, and no
`)` to close the link, so Markdown made no link of it.
- **So `&` is escaped too, the text says the link ends with a `)` after the last `}`, and the
page closes what is left open:** the True/False then built. With that text, 12 of 12 built
and passed, none needing a closer: three Accordions on HTML tags, three True/False questions
naming `cat.jpg`, five Question Sets (one in Ukrainian, three from a code tool with no
network), and a Drag the Words. No reply held a code block or the source a second time.
- **The archive line,** offered where a code tool runs: "where Node runs here and nothing could be
installed or downloaded" went to 1 of 6 runs with no code tool, wrongly; "where a command you
ran here found Node", to 0 of 1 run with one; "where you have a code tool", as the last
paragraph, to 1 of 2. As an item in a list of what the reply holds, 2 of 2 runs with a code
tool gave it and the run without one did not.

Links ran from 0.5 to 6.9 KB as written, and a Ukrainian one to 16.6 KB once a renderer escapes
its letters. A route-4 chat read 13 to 35 KB of the skill, most of it type files: the route's file is
2.1 KB, where the page's was 3.1. Haiku is a floor here: it shows the words are followed, not what a
chat app's renderer does with a link of several KB. That is the owner's run in ChatGPT.
- **The skill names no product** (2026-11-12, the owner's call). Its routes were told apart by
the apps they were measured in; they now say what each needs: a shell that reaches the npm
registry, Node and a download where npm cannot install, or nothing that runs or fetches. What a
Expand Down
82 changes: 38 additions & 44 deletions skills/h5p-author/references/build/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,46 @@ No package is built here. [The build page](https://missing-elements.github.io/h5
it in the user's browser from the source alone, with no install. The user plays it there, which is
its only check, and downloads it from there: it is **unverified** until they have.

**Hand the source over in a page that makes the link**, whether or not a command runs here (a
chat's code tool can be unavailable for hours), and whether or not you can tell how the chat
shows it. Copy the page below with the whole source in place of the line `SOURCE`, and every
other line as it is: change nothing in its script. The user's browser makes the link from the
source, so nothing compressed is typed or copied; a link copied into a reply from a command's
output can arrive damaged, so run no command for one.

- **In a chat**, write the page in one `html` code block, and give the source nowhere else in that
reply. Tell the user, in a line or two and in this order: first, to open the block as a page
with the chat's Preview and click *Build and play it*, which the chat may ask them to allow; only
then, as the way where their chat shows no Preview, to save the block as a file ending in `.html`
and open it.
- **Outside a chat**, as in a terminal, write the page to a file ending in `.html` beside the
source, and tell the user to open it.

```html
<!doctype html>
<meta charset="utf-8">
<title>Build and play</title>
<p><a id="link" target="_blank" rel="noopener">Making the link…</a></p>
<noscript id="source">
SOURCE
</noscript>
<script>
const source = document.getElementById('source').textContent.trim()
const link = document.getElementById('link')
new Response(new Blob([source]).stream().pipeThrough(new CompressionStream('deflate-raw'))).arrayBuffer().then((buffer) => {
let text = ''
for (const byte of new Uint8Array(buffer)) text += String.fromCharCode(byte)
link.href = 'https://missing-elements.github.io/h5p/build/#source=' + btoa(text).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
link.textContent = 'Build and play it'
}, (error) => { link.textContent = 'No link could be made here (' + error + '). Copy the source from the code block into https://missing-elements.github.io/h5p/build/' })
</script>
**Hand the source over as one link that you write yourself, with the source in it as JSON.** Write
no code block and run no command for it: the link is the whole hand-over, and your reply holds the
source once, inside it.

```markdown
[Build and play it](https://missing-elements.github.io/h5p/build/#source=SOURCE)
```

A source that names files gets no page: a page carries its text, not the files. Put the **whole
source in your reply**, in one `json` code block, and tell the user to paste it into the build
page at https://missing-elements.github.io/h5p/build/ and choose its files there. Never give that
address without the source: it builds nothing.
In place of `SOURCE`, write the whole source as JSON on one line. Write every character as it is,
letters of any language too, except these eight, which a link cannot hold as they are:

The build page lists every problem by its path, with a button that copies them for the chat: fix
them all and give a new page, or the whole source again.
| Character | Write |
| --- | --- |
| a space | `%20` |
| `%` | `%25` |
| `&` | `%26` |
| `\` | `%5C` |
| `(` and `)` | `%28` and `%29` |
| `<` and `>` | `%3C` and `%3E` |

Where Node runs here and nothing could be installed or downloaded, add this line, as it is, after
the page or the source: attached to a message, the archive builds the `.h5p` here.
So `"question": "<p>Is it (really) 100%?</p>"` is written
`"question":"%3Cp%3EIs%20it%20%28really%29%20100%25?%3C/p%3E"`. The link ends with a `)` right
after the source's last `}`.

```
To get the .h5p file here instead: download https://missing-elements.github.io/h5p/bundles/h5p-author-build.tar.gz (15 MB) and attach it to your next message.
```
Your reply holds:

- the link;
- one line asking the user to click it: the page builds the activity, plays it, and saves it as a
`.h5p`. Where the source names files, add that the page asks for them first: a link carries the
source's text, not its files;
- only where you have a code tool, this line, as it is, since attached to a message the archive
builds the `.h5p` here:

```text
To get the .h5p file here instead: download https://missing-elements.github.io/h5p/bundles/h5p-author-build.tar.gz (15 MB) and attach it to your next message.
```

Outside a chat, as in a terminal, a link this long may not open on a click: also write the source
to a file named after the activity with `.source.json`, and say that the build page opens it under
*Or open a file*.

The build page lists every problem by its path, with a button that copies them for the chat: fix
them all and give a new link.
Loading