Skip to content

feat(normalize, author): the page's build moves an mp4's index to the front - #259

Merged
alekswebnet merged 3 commits into
mainfrom
feat/page-faststart
Nov 20, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
feat/page-faststart

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Part of #218: item 5, "The build page moves an mp4's index to the front". Item 4 is #258; item 6 and the open question stay in #218.

What changes

  • The normalizer's remux plan moves into ./mp4 as faststartPlan(read, size), on Uint8Array and DataView rather than Buffer, like mp4Info beside it. It returns { status, detail, pieces, size }: each piece a range of the file or the rewritten index. Only the index is read whole.
  • mp4-faststart.mjs's planFaststart(file, base, size) is now a wrapper: the file's bytes in, the ranges shifted by base. The remux exists once, and normalizeArchive is unchanged.
  • The page's build lays out an mp4 or an m4a with its index first, as Node's build does through the normalizer. The file is a Blob of the given file's slices and the rewritten index, so no byte of the media is copied, and its CRC is that of what is stored. Every stored file is asked of the plan, which tells an ISO media file by its first eight bytes and leaves any other file, and one with its index first already, as given: the page keeps no list of extensions beside the normalizer's.
  • An index of containers nested deeper than a real one is left alone. The walk through moov went into every container, so a crafted file of a hundred thousand trak atoms inside each other ended it with a RangeError, in the normalizer too, before this change. It now stops eight deep (a real index nests four) and the file comes back skipped.

Before, a phone's video built on the build page could start playing only once it had arrived whole.

Release order: the normalizer first, and the publish check holds it

The page build imports faststartPlan by name, and npm's record of a version lists entries, not what they export. So check-pack-published.mjs now refuses to publish the author while packages/normalize is below 1.5.0, the first version with it:

  1. normalize 1.5.0 (minor, new export);
  2. then the author, whose workspace:^ publishes as ^1.5.0, which the same check then finds on npm.

Run today, with the normalizer at 1.4.1, the check stops with that instruction. I have not bumped anything.

Tests

  • normalize: 35, two new. faststartPlan on bytes in memory gives the same bytes as the file path, and leaves the bytes it read unchanged; a faststart file and a web page come back as one whole-file piece. The crafted index is skipped, and one nested as a real one is moved.
  • author: 280 Node and 2 Chromium tests. The page test now unzips the built package: the clip is stored, the same size, moov before mdat, and its CRC checks out on read.
  • embed 83, skills 82, type checks of normalize and author.

Docs

The author README ("In a page"), the normalizer README (faststartPlan), docs/compatibility.md, design/author.md, design/normalize.md and design/layout.md.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

6 issues found across 11 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="design/normalize.md">

<violation number="1" location="design/normalize.md:7">
P2: Adding `./mp4` as an exported subpath makes `mp4.mjs` public, so the next sentence's claim that the other modules 'stay free to change' no longer holds. Update that sentence to name `./mp4` (`mp4Info`, `faststartPlan`) as documented API, matching docs/compatibility.md.</violation>
</file>

<file name="packages/author/README.md">

<violation number="1" location="packages/author/README.md:382">
P2: The README names only mp4 and m4a, but the page build also moves the index of `.m4v` and `.mov` files (`ISO_MEDIA` in `lib/browser.mjs`), as the PR description states. List all four so the documented behavior matches the code.</violation>
</file>

<file name="packages/author/lib/browser.mjs">

<violation number="1" location="packages/author/lib/browser.mjs:20">
P3: The header comment names only mp4 and m4a, but this build also moves the index of m4v and mov files. Name all four containers so the doc matches the code and the PR description.</violation>

<violation number="2" location="packages/author/lib/browser.mjs:131">
P3: This extension list duplicates `ISO_MEDIA_EXTENSIONS` in the normalizer. If one list changes and the other does not, the page and Node builds will lay out different files. Export the set from the normalizer and gate on that instead of a second copy here.</violation>

<violation number="3" location="packages/author/lib/browser.mjs:131">
P2: The new `.m4v` and `.mov` branches are unreachable: `MediaStore` rejects those extensions before `laidOut()` runs, so page builds still cannot provide the advertised four-container support. Extend the author media whitelist and its naming/MIME rules consistently, or remove these dead alternatives.</violation>
</file>

<file name="packages/normalize/lib/mp4.mjs">

<violation number="1" location="packages/normalize/lib/mp4.mjs:293">
P2: The public planner recursively descends untrusted `moov` containers without a depth bound. A crafted nested-container chain can overflow the call stack instead of returning `skipped`; use an iterative walk or enforce a maximum nesting depth.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread design/normalize.md Resolved
Comment thread packages/author/README.md Resolved
Comment thread packages/author/lib/browser.mjs Resolved
Comment thread packages/normalize/lib/mp4.mjs Resolved
Comment thread packages/author/lib/browser.mjs Resolved
Comment thread packages/author/lib/browser.mjs Resolved
…he plan of every file, and the publish check holds the normalizer's version (#218)

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 7 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

…below it, and the file plan says its positions (#218)
@alekswebnet
alekswebnet merged commit 56e236f into main Nov 20, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant