@getv.design/embed 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,173 @@
+The vDesign Embed Licence, version 1.0
+
+Copyright © 2026 Sagar Saini. All rights not granted below are reserved.
+
+This licence lets you use the vDesign Embed free of charge, including in
+commercial products, and pass on copies of it as long as they are unchanged.
+By using, copying or redistributing the Software, You accept this licence.
+
+
+1. Definitions
+
+"Software" means the vDesign Embed: the JavaScript files, TypeScript
+declaration files and stylesheets in this package, in the form the Licensor
+publishes them, and any copy of them. It does not include the third-party
+components described in clause 6.
+
+"Licensor" means Sagar Saini, an individual. You can contact the Licensor at
+sagar@getv.design.
+
+"You" means the person or organisation that uses, copies or redistributes the
+Software under this licence.
+
+
+2. Grant
+
+The Licensor grants You a free, worldwide, non-exclusive, non-transferable,
+royalty-free licence to:
+
+  (a) use the Software for any purpose, including commercial purposes;
+  (b) copy it; and
+  (c) redistribute it unmodified, including as part of a website or an
+      application that You make, sell or give away.
+
+The people who use Your website or application may use the Software as part
+of it. They need nothing further from the Licensor to do so.
+
+
+3. Redistribution
+
+You may redistribute the Software bundled into Your own product, or serve it,
+as this package and under its own name, from npm or a public npm mirror such
+as a content delivery network, as long as:
+
+  (a) the copyright and licence notices in the Software, including the comment
+      at the start of each JavaScript file, are kept, in the code or in a
+      notices file that Your build tool produces from it; and
+  (b) when You redistribute the package as a whole, this licence and the file
+      THIRD_PARTY_NOTICES.txt go with it.
+
+Processing the Software with a bundler, minifier, transpiler or similar build
+tool, including tree-shaking, code-splitting and changing the module format,
+is not modification under this licence, as long as it does not change what the
+Software does. Configuring the Software through its documented options,
+styling it through its documented CSS custom properties, and calling its
+public interface are uses of it, not modifications.
+
+Everyone who receives a copy of the Software from You receives this licence
+from the Licensor directly.
+
+
+4. Restrictions
+
+Except as clauses 2 and 3 allow, You may not:
+
+  (a) modify the Software, or distribute a modified copy of it or a work based
+      on it (a product that includes the unmodified Software is not a work
+      based on it);
+  (b) decompile, disassemble or otherwise reverse engineer the Software;
+  (c) remove or change any copyright, licence or attribution notice in the
+      Software; or
+  (d) misrepresent where the Software came from, including by presenting it as
+      Your own work.
+
+Restrictions (a) and (b) apply only to the extent the law allows. Where
+applicable law expressly gives You a right to do something despite a
+restriction like these, this licence does not take that right away. Examples
+are Articles 5 and 6 of EU Directive 2009/24/EC (on the legal protection of
+computer programs) and section 52(1)(ab) and (ac) of the Indian Copyright Act,
+1957, which allow certain acts needed to study how a program works or to make
+an independently created program work with it.
+
+Nothing in this licence stops You from making a product that competes with
+vDesign, including one that reads or writes the .vd format.
+
+
+5. Your documents and the open format
+
+The Licensor claims no rights in the documents You open, render, present or
+edit with the Software, or in what the Software produces from them.
+
+The .vd format specification is published separately under the Creative
+Commons Attribution 4.0 International licence (CC BY 4.0). Anyone may
+implement the format, free of charge and without asking permission. This
+licence covers the Software only. See https://getv.design/docs/licence/.
+
+
+6. Third-party components
+
+This package also contains code and fonts made by others. They are not part
+of the Software, and are listed in THIRD_PARTY_NOTICES.txt with their licences
+in full. Those components are governed by their own licences, not by this one,
+and nothing in this licence limits the rights those licences give You.
+
+
+7. Trademarks
+
+This licence gives You no rights to the name "vDesign" or to any vDesign logo,
+except to say accurately that Your product uses the Software.
+
+You need not show any credit for the Software to the people who use Your
+product: the notices in the code, under clause 3, are the only ones You must
+keep. A visible "Made with vDesign" link is appreciated. The Software shows
+no watermark and needs no licence key.
+
+
+8. Network and data
+
+The Software sends no telemetry and collects no information about You or the
+people who use Your product. It makes network requests only for:
+
+  (a) font files, from the configured font location, which is the jsDelivr
+      content delivery network (cdn.jsdelivr.net) unless You set another;
+  (b) addresses that You, or the documents You give the Software, supply; and
+  (c) the Software's own files, from wherever You serve them.
+
+These requests are made by the browser or other runtime that runs the
+Software. The services they reach have their own terms and privacy practices.
+
+
+9. Versions and termination
+
+The Licensor may publish later versions of the Software under different terms.
+That does not change the licence of a version already published: the licence a
+version was published with is not revoked, except under this clause.
+
+If You breach this licence and do not cure the breach within 30 days after the
+Licensor notifies You of it, Your rights under this licence end, and You must
+stop using and redistributing the Software. That does not end the licence of
+anyone who received the Software from You and complies with this licence.
+
+
+10. No warranty; limitation of liability
+
+The Software is provided free of charge, "as is" and "as available", without
+warranty of any kind, express or implied, including any warranty of
+merchantability, fitness for a particular purpose, title or non-infringement,
+to the fullest extent the law allows. You use it at Your own risk.
+
+To the fullest extent the law allows, the Licensor is not liable for any
+indirect, incidental, special, consequential, exemplary or punitive damages,
+or for any loss of profits, revenue, data, business or goodwill, arising out of
+or in connection with the Software or this licence, however caused and on any
+theory of liability, even if the Licensor was told such loss was possible.
+
+To the fullest extent the law allows, the Licensor's total liability arising
+out of or in connection with the Software or this licence is limited to the
+greater of the amount You paid the Licensor for the Software and 100 US
+dollars (USD 100).
+
+Nothing in this licence excludes or limits any liability that cannot be
+excluded or limited by law, such as liability for fraud, or for death or
+personal injury caused by negligence.
+
+
+11. Governing law and courts
+
+This licence, and any dispute arising out of or in connection with it or the
+Software, are governed by the laws of India. The courts in India that have
+jurisdiction over the dispute have exclusive jurisdiction to settle it.
+
+This clause does not take away any protection You have, as a consumer, under
+the mandatory law of the country where You live, or any right You have under
+that law to bring proceedings in its courts.

package/README.md

@@ -1,3 +1,423 @@
-# Temporary Holding Version
+# @getv.design/embed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Render, present and edit vDesign (`.vd`) documents in any web page.
+
+Free to use, including commercially: no licence key, no watermark, and
+attribution is appreciated but not required. The code is proprietary, under
+the vDesign Embed Licence in `LICENSE`; the `.vd` format it reads is open, and
+anyone may implement it (see "Licence" below).
+
+**Not published yet.** This package is being built in steps; until the first
+release, nothing here is on npm, and the API may still change. While it is
+0.x, a minor version may change the API.
+
+The API reference, every option and event, is at
+https://getv.design/docs/embed/api/.
+
+## Quick start
+
+From npm, with a bundler:
+
+```sh
+npm install @getv.design/embed
+```
+
+```js
+import { view } from '@getv.design/embed/view';
+
+const text = '…'; // a .vd document, as text; or pass a URL or a Blob
+const handle = await view(document.querySelector('#design'), text);
+```
+
+Without a bundler, import the ES modules from a CDN. jsDelivr serves the
+package as published; import the entry file itself (not jsDelivr's `+esm`
+rebundling), so the editor and the font code still load only when needed:
+
+```html
+<div id="design"></div>
+<script type="module">
+  import { view } from 'https://cdn.jsdelivr.net/npm/@getv.design/embed@0.1.0/dist/view.js';
+
+  const text = await (await fetch('/designs/home.vd')).text();
+  await view(document.querySelector('#design'), text);
+</script>
+```
+
+Give the element a size in your stylesheet: the view fills it. Under a
+content security policy that refuses inline scripts, put the module in a file
+of your own and link the stylesheets as "Styles and content security policy"
+below describes.
+
+The entries:
+
+| Import                             | What it does                                                       |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `@getv.design/embed/static`                     | A document in, an SVG string out. No DOM: Node 22.3+ and browsers. |
+| `@getv.design/embed/view`                       | Show a document in an element, page through it, present it.        |
+| `@getv.design/embed/edit`                       | The vDesign editor, with its floating toolbar.                     |
+| `@getv.design/embed`                            | `mount(el, source, { mode })`: loads one of the above on demand.   |
+| `@getv.design/embed/view.css`, `@getv.design/embed/edit.css` | The styles, for a strict content security policy.                  |
+| `@getv.design/embed/fonts/*`                    | The Inter faces, to serve yourself.                                |
+
+## Static SVG
+
+`@getv.design/embed/static`: a document in, an SVG string out, with no DOM. Runs in
+Node 22.3+ and in browsers. 22.3 is when `process.getBuiltinModule`
+arrived, which is how exact fonts are read from disk without a Node import.
+
+```js
+import { parse, renderSvg } from '@getv.design/embed/static';
+
+const { document, problems } = parse(text); // never throws; problems lists what is wrong
+const svg = await renderSvg(document); // or renderSvg(text), a URL, or a Blob
+const second = await renderSvg(document, { page: 1 }); // one page, by 0-based index or id
+```
+
+By default text is measured approximately, without font files, so line breaks
+can differ slightly from the app's. `fonts: 'exact'` lays text out from the
+font files the app exports with, so lines break where the app's SVG export
+breaks them:
+
+```js
+const svg = await renderSvg(text, {
+  fonts: 'exact',
+  onProblems: (problems) => console.log(problems),
+});
+```
+
+In Node the faces are read from the package's own `fonts/` folder; in a
+browser they are fetched from `fontBase` (see "Fonts" below). The disk is used
+only where Node can actually read it: a browser bundle whose bundler kept a
+`file:` URL from the build machine (webpack 5 does) fetches from `fontBase`
+like any other page. The SVG names
+the family, `Inter`, and carries no font files of its own. If a face cannot be
+read, the SVG is drawn approximately and `onProblems` is given a
+`fonts-unavailable` warning; `renderSvg` does not reject for it.
+
+## View and present
+
+`@getv.design/embed/view`: show a document in an element, page through it, and present it.
+
+```js
+import { view } from '@getv.design/embed/view';
+
+const handle = await view(el, text, { fit: 'page', page: 0 }); // or a URL, a Blob, a parsed document
+handle.on('problems', (problems) => console.log(problems)); // called at once with the current list
+handle.goTo('pricing'); // a page by id or 0-based index
+await handle.load(newText); // redraws in place; unchanged parts are not rebuilt
+const play = await handle.play(); // present over the view; Escape comes back
+handle.destroy(); // el is left empty, and image URLs are released
+```
+
+The view adds one `<div>` inside `el` and fills it, so give `el` a size. A
+plain wheel over it scrolls your page as usual; Ctrl or ⌘ with the wheel, or a
+trackpad pinch, zooms, and middle-drag or Space-drag pans. `interactive: false`
+turns all of that off. A page
+is a top-level frame that is not hidden, counted the same way by `renderSvg`.
+Images are drawn from `blob:` URLs, so a page with a content security policy
+needs `img-src blob:`.
+
+`mount(el, source, { mode: 'view' })` from `@getv.design/embed` does the same and loads the
+view code only when called; `mode: 'play'` opens straight into the
+presentation, and that handle's `destroy()` removes the view under it too.
+
+The view inserts one `<style>` into the page's head; "Styles and content
+security policy" below has the alternative for a page that refuses inline
+styles.
+
+## Edit
+
+`@getv.design/embed/edit`: the vDesign editor in your page, with its floating toolbar.
+
+```js
+import { edit } from '@getv.design/embed/edit';
+
+const editor = await edit(el, text, { fit: 'page' }); // the same sources and options as view()
+editor.on('change', (event) => save(event.text())); // once per undo step; text() is the whole .vd file
+editor.getText(); // the same, at any time: the design, then any images
+editor.undo();
+editor.redo();
+const handle = await editor.view(); // back to a view, where the person was looking
+editor.destroy(); // el is left empty
+```
+
+From a view, `await handle.edit()` swaps the view for an editor in the same
+element and keeps the camera; `mount(el, source, { mode: 'edit' })` opens
+straight into one. The editor's code (about 85 KB gzip) loads only then:
+nothing that views a document downloads it.
+
+`change` fires once for each step undo would take back: a whole drag is one,
+when the pointer comes up, and so are an undo and a redo. `text()` composes the
+file only when you call it. A picture pasted or dropped onto the canvas goes
+into the document's own payload, so `getText()` carries it and nothing is
+uploaded anywhere. `toolbar: false` leaves out the toolbar and the context
+menu, for a host with its own controls.
+
+The editor behaves on a page as the view does: a plain wheel scrolls your
+page, Ctrl or ⌘ with the wheel zooms, and any number of editors can share a
+page. A plain click selects, so a link is followed on ⌘-click (Ctrl elsewhere),
+and only an `https:` or `mailto:` one: to `onLink`, or else into a new tab
+with `noopener`. `fit` frames the document when the editor opens, and again
+when `el` changes size only until the person moves the camera.
+
+The editor's chrome is drawn for the default dark `surface`. With a light
+one, also set `--vd-page-label` and `--vd-page-label-hover` on `el` (the
+colours of each page's name above its corner), for example to
+`rgb(0 0 0 / 0.5)` and `#1a1a1f`.
+
+## Fonts
+
+By default (`fonts: 'exact'`) the view lays text out from the same font files
+the app exports with, so lines break where the app breaks them. It draws at
+once with your page's fonts, loads the font code (about 150 KB gzip, only now),
+fetches only the faces the document uses (one `.woff2` per weight and style),
+and lays the text out again once when they arrive. A document opened later
+with `load()` has any new face fetched before it is drawn.
+`handle.on('fonts', (state) => …)` says `'exact'` once the files are in use.
+
+If a face cannot be fetched, the view stays on your page's fonts, `problems`
+gains a `fonts-unavailable` warning and the `fonts` event says `'browser'`;
+nothing throws. `fonts: 'browser'` skips all of this.
+
+The editor measures the same way. A face that an edit brings in, such as a
+word made bold, is fetched once the document has been still for a moment. If
+one cannot be fetched the editor carries on with your page's fonts; the editor
+has no `problems` or `fonts` event yet to say so.
+
+### Where the faces come from
+
+The faces come from `fontBase`, by default this package's `fonts/` folder on
+jsDelivr (`https://cdn.jsdelivr.net/npm/@getv.design/embed@0.1.0/fonts/`). That means
+your readers' browsers request the faces from jsDelivr, and a content security
+policy needs it in `connect-src`. To keep those requests on your own origin,
+copy `node_modules/@getv.design/embed/fonts/` to your site and point `fontBase` at it:
+
+```js
+await view(el, text, { fontBase: '/assets/vdesign-fonts/' });
+```
+
+The faces are Inter, under the SIL Open Font License (`fonts/OFL.txt`).
+
+## Styles and content security policy
+
+The embed's styles reach the page by one of two routes.
+
+1. **Injected (the default).** The view inserts one
+   `<style id="vd-viewer-styles">` into the page's head, and the editor
+   another, `<style id="vd-editor-styles">`. Nothing to set up, but a
+   content security policy must allow `style-src 'unsafe-inline'`.
+2. **Linked.** Serve the package's `view.css` (and `edit.css`, if you edit)
+   and link them under those ids. The view and the editor find the id and
+   insert nothing, so the page needs no `'unsafe-inline'`:
+
+   ```html
+   <link rel="stylesheet" id="vd-viewer-styles" href="/view.css" />
+   <link rel="stylesheet" id="vd-editor-styles" href="/edit.css" />
+   ```
+
+   Link them before the embed runs, from your own origin or from the CDN
+   (`https://cdn.jsdelivr.net/npm/@getv.design/embed@0.1.0/view.css`). The id is what
+   the embed looks for: linked without it, the stylesheet still works, but
+   the embed inserts its `<style>` as well.
+
+Either way, the theme is a set of CSS custom properties, which you can set on
+the element you give the embed; `--vd-accent`, for example, colours the
+selection.
+
+The view, the player and the editor run under a policy with no
+`'unsafe-inline'` once the styles are linked. `npm run embed:check` runs
+every mode under this one, with the package served from the page's own
+origin:
+
+```text
+default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
+```
+
+What each part is for:
+
+- `script-src`: wherever you serve the package's `dist/` from.
+- `style-src`: wherever you serve `view.css` and `edit.css` from. Without them
+  linked, the embed injects a `<style>` and needs `'unsafe-inline'`.
+- `img-src blob:` for a document's images, which are drawn from object URLs.
+  `img-src data:` for the editor, whose cursors are `data:` images.
+- `connect-src`: the document URLs you pass, and `fontBase`. With the default
+  `fontBase`, that means `https://cdn.jsdelivr.net`; served yourself, your own
+  origin.
+- `font-src` needs nothing for the embed: the faces are fetched as bytes and
+  handed to the page as `FontFace`s, which no `font-src` governs.
+
+Served from jsDelivr instead, the same policy needs
+`https://cdn.jsdelivr.net` in `script-src`, `style-src` and `connect-src`.
+
+`renderSvg` output carries a `style="mix-blend-mode: …"` attribute on any
+layer with a blend mode. Inlined into a page under `style-src 'self'`, those
+layers lose their blend mode and draw normally; shown as an `<img>`, the SVG
+is unaffected.
+
+## Host page CSS
+
+There is no shadow root, so your page's CSS reaches the embed. Every class it
+uses starts with `vd-`, which keeps its rules and yours from colliding, but a
+reset that targets elements still applies. `npm run embed:check` runs the
+editor under a reset like a CSS framework's preflight (`svg { display: block }`,
+`button { all: unset }`, `* { color: red }`, border-box sizing), and this is
+what it does:
+
+- **The drawing is unaffected.** A document's colours, sizes and fonts are
+  attributes on its SVG, which element selectors do not reach, and the theme
+  variables still apply: `--vd-accent` set on your element colours the
+  selection.
+- **`* { color: … }` recolours the editor's chrome.** The toolbar's icons and
+  the context menu's labels take your colour, and a disabled menu item no
+  longer looks dimmed, because each element gets the colour directly rather
+  than inheriting the editor's.
+- **`button { all: unset }` and border-box resets resize the chrome.** The
+  toolbar grows (348 by 32 pixels became 376 by 44), and the context menu's
+  shortcut column is cut off at its right edge. The view draws no buttons, so
+  only the editor is affected.
+
+If your stylesheet has rules like these, scope them to your own content so
+they do not match inside the element you give the embed.
+
+## Not yet
+
+- **Arrow keys do not move a selected shape** in the editor. They move a
+  path's points while you edit them, and nothing else yet; drag instead.
+- **No `problems` or `fonts` event on the editor**, so a face it could not
+  fetch goes unreported (see "Fonts").
+
+Not planned for the first release, in no particular order: shadow-root
+isolation, the inspector and layers panels, a custom element, React or Vue
+wrappers, an IIFE or UMD build, images in Node.
+
+## Attribution
+
+Not required. The notices in the code, the comment at the top of each file,
+are the only credit the licence asks you to keep, and a bundler that moves
+them into a notices file keeps them well enough. If you would like to say
+where your designs come from, a "Made with vDesign" link to
+https://getv.design is appreciated.
+
+## Licence
+
+Free to use under the vDesign Embed Licence, in `LICENSE`: commercial use and
+unmodified redistribution are allowed, attribution is appreciated but not
+required, and there is no watermark or licence key. Bundling, minifying and
+code-splitting it are not modification. The code is proprietary: you may not
+change it or pass on a changed copy. The `.vd` format itself is open, under
+CC BY 4.0, and anyone may implement it: see https://getv.design/docs/licence/. Third-party code and fonts in the
+package, and their licences in full, are listed in `THIRD_PARTY_NOTICES.txt`.
+
+## Working on it
+
+The name above is read from `publishName` in this workspace's `package.json`,
+the only place it is written. `npm run embed:build` writes the package into
+`out/`; `npm run embed:pack` builds it, packs it into a tarball in
+`packages/embed/` (gitignored, never published), and prints the tarball's
+contents.
+`out/package.json` stays `"private": true` until the licence has been reviewed
+(below).
+
+`npm run embed:check` builds the package and runs it in Chromium
+(Playwright, from `check/`): host pages under a strict content security policy
+with no `'unsafe-inline'`, the styles linked as above and the faces served
+from the same origin. It covers `/static`, `/view`, presenting and `/edit`,
+exact fonts and their failure, the wheel, links, several embeds on one page,
+`destroy()`, and the reset-heavy host above. It needs a browser
+(`npx playwright install chromium`), so it is not part of `npm run verify`;
+run it when you change this package or anything it bundles.
+
+The build writes `THIRD_PARTY_NOTICES.txt` from esbuild's metafile
+(`scripts/notices.mjs`), so it lists exactly the packages whose code ships. It
+fails on a licence outside MIT, ISC, Apache-2.0, 0BSD, BSD-2-Clause,
+BSD-3-Clause and OFL-1.1, and on a package with no licence file unless
+`notices-overrides.json` says where its text came from (an override may also
+fill a missing licence, never replace one). Code that is neither under
+`node_modules` nor in one of our workspaces, such as a linked package, is
+refused, and a refused build leaves no `out/`. Adding a licence to
+that list is a licensing decision, not a build fix. Every published `.js` file
+starts with a licence banner, and licence comments in bundled code are kept at
+the end of the file.
+
+## Publishing (owner only)
+
+**This package is published only by `.github/workflows/publish-embed.yml`.
+Nobody, person or agent, runs `npm publish` locally**; `--dry-run` is the one
+exception.
+
+On every merge to `main` that touches this package, the workspaces it bundles
+(core, engine, renderer, fonts, viewer, editor), `package-lock.json` or the
+workflow, the workflow installs, runs this package's tests and
+`npm run embed:check`, builds `out/`, runs the publish gate, and then asks
+`scripts/publish-decision.mjs`:
+
+- **Publish:** the version in `package.json` is not on npm. The workflow
+  publishes the `out/` it just checked, with `--access public`, then waits up
+  to five minutes for jsDelivr to serve a font from it.
+- **Skip:** that version is on npm, and the published tarball holds exactly
+  the files this build packs. Nothing that ships changed.
+- **Bump needed:** that version is on npm with different files. The run
+  fails with "bump the version in packages/embed/package.json".
+
+A pull request runs the same check, with no token in reach, and its summary
+says which of the three its merge would do; a bump shows red there first. So a
+PR that changes what ships, this README included, raises `version` in the same
+PR. Locally, after `npm run embed:build`, run
+`node packages/embed/scripts/publish-decision.mjs` to ask the same question.
+
+The comparison works because the build is deterministic: two clean builds give
+byte-identical `out/` and tarballs. Keep it so. A timestamp, an absolute path
+or an unordered list in the output would make every merge look like a change.
+
+The workflow authenticates with the `NPM_TOKEN` secret: a granular npm token
+with read and write on the package's scope and nothing else, allowed to bypass
+2FA. It expires; renew it before it does, or the next publish fails at the
+publish step. There is no provenance, which npm makes only from a public
+repository. Once the package exists, npm trusted publishing (OIDC) can replace
+the token: register the workflow on npmjs.com as the package's trusted
+publisher (it already has `id-token: write`), then delete the secret. Whether
+npm accepts trusted publishing from a private repository is unconfirmed, so
+try it with the token still in place.
+
+### The licence gate
+
+Nothing publishes until the licence has been reviewed by a lawyer and the owner
+has committed a record of that review. `scripts/gate.mjs` is the lock: the build
+writes `"private": false` into `out/package.json` only when it passes, the
+workflow runs it before deciding, and the manifest's `prepublishOnly` runs it
+again, so `npm publish` (and `npm publish --dry-run`) from `out/` fails while it
+is closed. Notes for the reviewer are in `LICENSE-REVIEW.md`, which is not
+packed.
+
+**Agents never create or edit `legal-review.json`.** The record is the owner's
+statement that the review happened. To make it:
+
+1. Have `LICENSE` reviewed, with `LICENSE-REVIEW.md` as the brief. Make the
+   changes advised, and remove the `DRAFT` line at the top.
+2. Hash the licence exactly as it will ship:
+
+   ```sh
+   shasum -a 256 packages/embed/LICENSE
+   ```
+
+3. Commit `packages/embed/legal-review.json`, with the hash from step 2:
+
+   ```json
+   {
+     "reviewed": true,
+     "by": "Name of the reviewer",
+     "date": "2026-11-02",
+     "licenceSha256": "the 64 hex digits shasum printed"
+   }
+   ```
+
+The workflow never publishes from a saved `.tgz` and never with
+`--ignore-scripts`: npm runs `prepublishOnly` only when publishing a folder, so
+either would skip the gate's second check and rely on `"private"` alone.
+`.gitattributes` marks `packages/embed/LICENSE` as `-text`, so git never
+rewrites its line endings and the hash is the same on every platform.
+
+Any later edit to `LICENSE` closes the gate again until the record's hash is
+updated, so the text that ships is always the text that was reviewed. Run
+`node packages/embed/scripts/gate.mjs` to see whether the gate is open and why
+not.