@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/pretui-css.gts

@@ -0,0 +1,380 @@
+// Pretui — kit-wide CSS policy: the caller-value guard and the stacking scale.
+//
+// Two things live here because both are *authorities*: there must be exactly
+// one of each in the kit, and every component defers to it rather than
+// re-deciding locally.
+//
+// ─────────────────────────────────────────────────────────────────────────
+// 1. `cssValue` — the guard for caller-supplied strings that reach CSS
+// ─────────────────────────────────────────────────────────────────────────
+//
+// A hue is routed through nearly every component, and it arrives as a
+// caller string. Interpolating that string into an inline style and handing
+// it to `htmlSafe` lets `red; background: url(https://evil/x)` inject
+// arbitrary declarations — `htmlSafe` means "I have already made this safe",
+// and nothing had.
+//
+// The guard is an ALLOWLIST, not a sanitizer: it validates and returns the
+// value unchanged, or returns `undefined` for anything it does not fully
+// understand. It never strips-and-continues, because strip-and-continue is
+// how a value that looked harmless after cleaning turns out not to be.
+// Callers build the declaration from the validated value, so the property
+// name is always an authored literal and only the value is ever in doubt.
+//
+// Numeric interpolations clamped through `Math` are already safe and do not
+// need this — a `number` cannot carry a semicolon. Strings always do.
+//
+// ─────────────────────────────────────────────────────────────────────────
+// 2. `--pretui-z-*` — the stacking scale
+// ─────────────────────────────────────────────────────────────────────────
+//
+// The kit's floating surfaces (Popup, and Popover through it; Dialog,
+// Drawer, Tooltip, Menu and the other dropdowns; Toaster) take their tier
+// from one scale, so they order among themselves and a host can slot its own
+// chrome between them.
+//
+// The order, and why it is this order:
+//
+//   base    0    in-flow content. Nothing needs to say this; it is the floor.
+//   raised  1    layering INSIDE one component's own box — a sliding
+//                highlight under its labels, a floating label over its
+//                field. Never competes with anything outside the component.
+//   sticky  10   sticky rows, columns and toolbars pinned inside a scroll
+//                container. Above content because it must cover it while
+//                scrolling; far below every floating surface, because a
+//                menu opened FROM a sticky toolbar has to clear it.
+//   sticky-header 11
+//                the one place two sticky planes cross: a pinned header cell
+//                over a pinned first column. It is deliberately adjacent to
+//                `sticky` rather than a tier of its own.
+//   scrim   50   the invisible outside-click catcher that belongs to a
+//                floating surface. Always one step BELOW the surface it
+//                dismisses and above everything the surface covers — a scrim
+//                that outranks its own panel eats the panel's clicks.
+//   dropdown 60  Menu (MenuPanel), MultiSelect, TreeSelect, Cascader,
+//                NavigationMenu, Mentions, EmojiPicker and Autocomplete.
+//                Anchored to a trigger, dismissed by an outside click, and
+//                always subordinate to a panel that may contain it. Select and
+//                Combobox render boxel-ui's listbox, which takes boxel-ui's
+//                own layer (above toast), and CommandPalette is a modal
+//                <dialog> in the top layer.
+//   overlay 70   Popup and Popover — a deliberate floating panel. Above
+//                dropdown because a Popover can contain a Select, and the
+//                containing panel must never paint under its own content.
+//   tooltip 80   a tooltip describes whatever is under the pointer, and that
+//                may be an item inside a dropdown or a popover. It is small,
+//                transient and non-interactive, so nothing is lost by it
+//                being the highest non-modal tier.
+//   dialog  90   Dialog and Drawer. FALLBACK ONLY: both use native
+//                `<dialog>` + `showModal()`, which promotes them to the top
+//                layer, above every z-index on the page regardless of value.
+//                Nothing reads this token; it records the intended rank
+//                rather than leaving it implied by the platform.
+//   toast   100  the last word. A toast reports something that just happened
+//                and must stay readable over whatever is open, including a
+//                modal — so it is the only tier deliberately above `dialog`.
+//                Toaster's fixed region and SkipLink take it; a bare Toast is
+//                in flow and takes no tier, so whatever positions one owns
+//                its z-index.
+//
+// The numbers are gapped so a host can interleave its own chrome (a global
+// nav at 65, an assistant panel at 85) without editing Pretui.
+//
+// **Consumption rule.** A component that stacks against OTHER components
+// writes `z-index: var(--pretui-z-<tier>, <the number above>)`. The literal
+// fallback is not optional and is not a guess — it is this table, restated,
+// so a host that has never defined these tokens renders in exactly the same
+// order; a host redefines a token to move a whole tier at once. Layering
+// inside one component's own box (a 1, 2 or 3) is the `raised` role and
+// stays literal. Exceptions that still pick their own number: PageScaffold's
+// skip link (20) and sticky masthead (10), FloatButton (--pretui-float-z, 20)
+// and Backdrop (--pretui-backdrop-z, 50).
+
+import { htmlSafe } from '@ember/template';
+
+// ── The caller-value guard ───────────────────────────────────────────────
+
+/**
+ * Every character a caller value may contain. Notably absent, and each for a
+ * reason a comment should record:
+ *
+ *   `;` `:`   would end the declaration and start another one — the whole
+ *             injection. Callers supply a VALUE, never a declaration.
+ *   `{` `}`   would close the style attribute's implied block context.
+ *   `<` `>`   `</style>` and friends.
+ *   `"` `'`   quoted strings are only needed by `url()` and `content()`,
+ *             neither of which is allowed.
+ *   `\`       CSS escapes (`\3b` is a semicolon) would defeat every rule above.
+ *   `@` `!`   at-rules and `!important`, both forbidden by kit law anyway.
+ *
+ * `*` and `/` survive because `calc()` needs them; the comment sequences they
+ * can form are rejected separately.
+ */
+const ALLOWED_CHARS = /^[A-Za-z0-9_\-#%.,()+*/ ]+$/;
+
+/**
+ * Functions a caller value may call. Anything not on this list — `url`,
+ * `image-set`, `element`, `attr`, `expression`, `-moz-binding` — is rejected
+ * outright rather than pattern-matched, so a function invented after this
+ * code was written is denied by default.
+ */
+const ALLOWED_FUNCTIONS = new Set([
+  // indirection
+  'var',
+  'env',
+  // math
+  'calc',
+  'min',
+  'max',
+  'clamp',
+  'round',
+  'abs',
+  // color
+  'rgb',
+  'rgba',
+  'hsl',
+  'hsla',
+  'hwb',
+  'lab',
+  'lch',
+  'oklab',
+  'oklch',
+  'color',
+  'color-mix',
+  // gradients. Their ARGUMENTS are still validated by the same character and function
+  // allowlist, so admitting the names widens nothing: `url()` and `attr()`
+  // remain rejected wherever they appear, at any nesting depth.
+  'linear-gradient',
+  'radial-gradient',
+  'conic-gradient',
+  'repeating-linear-gradient',
+  'repeating-radial-gradient',
+  'repeating-conic-gradient',
+  'light-dark',
+  // easing — `@ease`/`@easing` knobs are caller strings too, and these take
+  // nothing but numbers and keywords, so they add no injection surface
+  'cubic-bezier',
+  'steps',
+  'linear',
+]);
+
+/** `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` — nothing else may follow a `#`. */
+const HEX = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+/** A `(` must be the tail of a function name, never a bare grouping paren. */
+const CALL = /([A-Za-z][A-Za-z0-9-]*)?\(/g;
+
+/** Anything starting `#` up to the next separator. */
+const HEXISH = /#[^\s,()]*/g;
+
+/** Longer than any legitimate color, length or gradient stop list. */
+// Bounds the parser's work; generated gradient tracks run past 1000
+// characters (a 32-step channel track is 1069), so the cap sits well above.
+const MAX_VALUE_LENGTH = 4096;
+
+/** Deeper than `color-mix(in oklch, var(--a, oklch(…)) 40%, var(--b))`. */
+const MAX_DEPTH = 5;
+
+/**
+ * Validate a caller-supplied CSS value against a conservative allowlist.
+ *
+ * Returns the trimmed value when every character, function call, hex literal
+ * and paren in it is understood, and `undefined` otherwise. There is no
+ * middle outcome: a value is passed through intact or dropped whole.
+ *
+ * @param raw anything a caller handed us — typed `unknown` because at a
+ *   component boundary an `@arg` declared `string` can still arrive as
+ *   `null`, a number, or an object.
+ */
+export function cssValue(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') {
+    return undefined;
+  }
+  let value = raw.trim();
+  if (value.length === 0 || value.length > MAX_VALUE_LENGTH) {
+    return undefined;
+  }
+  if (!ALLOWED_CHARS.test(value)) {
+    return undefined;
+  }
+  // A comment can hide a semicolon from a human reader but not from the
+  // parser, so neither delimiter may appear.
+  if (value.includes('/*') || value.includes('*/')) {
+    return undefined;
+  }
+  // Balanced and shallow. An unbalanced `var(--x` would swallow whatever the
+  // stylesheet says next.
+  let depth = 0;
+  for (let i = 0; i < value.length; i++) {
+    let ch = value[i];
+    if (ch === '(') {
+      depth++;
+      if (depth > MAX_DEPTH) {
+        return undefined;
+      }
+    } else if (ch === ')') {
+      depth--;
+      if (depth < 0) {
+        return undefined;
+      }
+    }
+  }
+  if (depth !== 0) {
+    return undefined;
+  }
+  // Every call is a known function; no anonymous groups.
+  CALL.lastIndex = 0;
+  let call = CALL.exec(value);
+  while (call !== null) {
+    let name = call[1];
+    if (name === undefined || !ALLOWED_FUNCTIONS.has(name.toLowerCase())) {
+      return undefined;
+    }
+    call = CALL.exec(value);
+  }
+  // Every `#` introduces a well-formed hex color.
+  HEXISH.lastIndex = 0;
+  let hex = HEXISH.exec(value);
+  while (hex !== null) {
+    if (!HEX.test(hex[0])) {
+      return undefined;
+    }
+    hex = HEXISH.exec(value);
+  }
+  return value;
+}
+
+/**
+ * A property name we are willing to write: a custom property, or a plain
+ * lowercase CSS identifier. Callers never supply this — it is an authored
+ * literal at every call site — but validating it keeps the contract total.
+ */
+const PROPERTY = /^(?:--[A-Za-z0-9_-]+|[a-z][a-z0-9-]*)$/;
+const NUMERIC = /^-?(?:\d+\.?\d*|\.\d+)$/;
+
+/**
+ * Build one `property: value` declaration from a validated caller value.
+ * Returns `undefined` when the value fails `cssValue`, so a rejected value
+ * falls through to whatever the stylesheet's own fallback is — the caller
+ * loses their override, never the component's rendering.
+ */
+export function cssDeclaration(
+  property: string,
+  raw: unknown,
+): string | undefined {
+  let value = cssValue(raw);
+  if (value === undefined || !PROPERTY.test(property)) {
+    return undefined;
+  }
+  return property + ': ' + value;
+}
+
+/**
+ * The numeric counterpart to `cssValue`. A component that interpolates a
+ * caller-supplied NUMBER into a style attribute — a size, an intensity, a
+ * thickness — cannot use `cssValue`, which only accepts strings, and an
+ * unguarded `${value}` puts whatever the caller passed into the declaration.
+ * Glint rejects a string at a typed call site, but a field-fed value is
+ * untyped, so the guard belongs here rather than in the type.
+ *
+ * Accepts a finite number, or a string that is nothing but a number.
+ * Everything else is rejected, so the caller's declaration is dropped whole
+ * rather than partially applied.
+ *
+ * An in-range value passes; an OUT-OF-RANGE one clamps rather than being
+ * rejected, which is the one place this guard's contract differs from
+ * `cssValue`'s pass-or-reject. That is deliberate: a clamp keeps the
+ * direction of the caller's intent where a reject would substitute the
+ * component's own default and lose it — `@rest={{2}}` on Spotlight means "as
+ * opaque as it goes", and 1 delivers that where 0.34 does not. The bounds are
+ * a sanity range, not a type: they exist so a hostile `1e9` cannot lay out a
+ * page, not to validate the argument.
+ */
+export function cssNumber(
+  raw: unknown,
+  min: number,
+  max: number,
+): number | undefined {
+  let n: number;
+  if (typeof raw === 'number') {
+    n = raw;
+  } else if (typeof raw === 'string' && NUMERIC.test(raw.trim())) {
+    n = Number(raw);
+  } else {
+    return undefined;
+  }
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : undefined;
+}
+
+/**
+ * The one-line swap for a `style=` binding: a validated single-declaration
+ * SafeString, or `undefined`.
+ */
+export function cssStyle(property: string, raw: unknown) {
+  let decl = cssDeclaration(property, raw);
+  return decl === undefined ? undefined : htmlSafe(decl);
+}
+
+/**
+ * Join several declarations — typically a mix of `cssDeclaration` results and
+ * authored numeric strings — into one SafeString, dropping the rejected ones.
+ * Returns `undefined` when nothing survived, so the attribute is omitted
+ * rather than rendered empty.
+ */
+export function cssStyleFrom(parts: (string | undefined)[]) {
+  let kept = parts.filter(
+    (p): p is string => typeof p === 'string' && p.length > 0,
+  );
+  return kept.length > 0 ? htmlSafe(kept.join('; ')) : undefined;
+}
+
+// ── The stacking scale ───────────────────────────────────────────────────
+
+/** Named tiers in the Pretui stacking scale, in painting order. */
+export type PretuiZLayer =
+  | 'base'
+  | 'raised'
+  | 'sticky'
+  | 'sticky-header'
+  | 'scrim'
+  | 'dropdown'
+  | 'overlay'
+  | 'tooltip'
+  | 'dialog'
+  | 'toast';
+
+/**
+ * The canonical value of every tier. This is the same table as the header
+ * comment and as every `var(--pretui-z-*, N)` fallback in the kit; it is
+ * exported so a host that must interleave its own chrome can read the tiers
+ * rather than copy the numbers.
+ */
+export const PRETUI_Z: Readonly<Record<PretuiZLayer, number>> = Object.freeze({
+  base: 0,
+  raised: 1,
+  sticky: 10,
+  'sticky-header': 11,
+  scrim: 50,
+  dropdown: 60,
+  overlay: 70,
+  tooltip: 80,
+  dialog: 90,
+  toast: 100,
+});
+
+/** The custom-property name for a tier. */
+export function zVarName(layer: PretuiZLayer): string {
+  return '--pretui-z-' + layer;
+}
+
+/**
+ * The scale as CSS custom properties, for a host stylesheet that
+ * wants to declare them explicitly. Declaring them changes nothing on its
+ * own — every consumer already falls back to these exact numbers — but it
+ * gives one place to shift a whole tier.
+ */
+export const PRETUI_Z_SCALE_CSS: string = (
+  Object.keys(PRETUI_Z) as PretuiZLayer[]
+)
+  .map((layer) => zVarName(layer) + ': ' + PRETUI_Z[layer] + ';')
+  .join('\n  ');

package/bundled-realms/pretui/pretui-primitives.gts

@@ -0,0 +1,162 @@
+// Shared control vocabulary. @tone picks the hue (sets --pretui-tone/--pretui-tone-on),
+// @appearance picks the recipe that reads those vars, @size sets host font-size only
+// (everything inside is em), and @variant is sugar over the two axes.
+export type PretuiTone =
+  | 'neutral'
+  | 'primary'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'attention';
+export type PretuiAppearance =
+  | 'accent'
+  | 'filled'
+  | 'outlined'
+  | 'filled-outlined'
+  | 'plain'
+  | 'link';
+export type PretuiSize = 'xs' | 's' | 'm' | 'l' | 'xl';
+
+export const PRETUI_TONES = [
+  'neutral',
+  'primary',
+  'info',
+  'success',
+  'warning',
+  'danger',
+  'attention',
+] as const;
+export const PRETUI_APPEARANCES = [
+  'accent',
+  'filled',
+  'outlined',
+  'filled-outlined',
+  'plain',
+  'link',
+] as const;
+export const PRETUI_SIZES = ['xs', 's', 'm', 'l', 'xl'] as const;
+
+// Alias layer: a component accepts other vocabularies' names for the same knob and
+// resolves them in a getter; the canonical name stays the taught one. Values notify
+// through @onChange and layers through @onOpenChange, with on<Noun>Change as aliases.
+
+/** First value the caller actually supplied. Canonical name goes first. */
+export function firstDefined<T>(...values: (T | undefined)[]): T | undefined {
+  for (let v of values) {
+    if (v !== undefined) {
+      return v;
+    }
+  }
+  return undefined;
+}
+
+/** Fire every notify handler supplied, canonical first; two handlers fire both rather than dropping one. */
+export function emit<A extends unknown[]>(
+  handlers: readonly (((...args: A) => void) | undefined)[],
+  ...args: A
+): void {
+  for (let h of handlers) {
+    h?.(...args);
+  }
+}
+
+// Alias spellings for the middle steps of the house scale xs|s|m|l|xl.
+// Null-prototype so a typed 'constructor' misses the table instead of hitting Object.prototype.
+const SIZE_ALIASES: Record<string, PretuiSize> = Object.assign(
+  Object.create(null) as Record<string, PretuiSize>,
+  {
+    xs: 'xs',
+    s: 's',
+    m: 'm',
+    l: 'l',
+    xl: 'xl',
+    sm: 's',
+    md: 'm',
+    lg: 'l',
+    default: 'm',
+    small: 's',
+    medium: 'm',
+    large: 'l',
+    middle: 'm',
+  } as const,
+);
+/** Every `@size` spelling accepted, narrowed to the house scale. */
+export type PretuiSizeArg =
+  | PretuiSize
+  | 'sm'
+  | 'md'
+  | 'lg'
+  | 'default'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'middle';
+
+export function resolveSize(
+  size: string | undefined,
+  fallback: PretuiSize = 'm',
+): PretuiSize {
+  return (size ? SIZE_ALIASES[size] : undefined) ?? fallback;
+}
+
+// House tone is 'danger'; 'destructive' lands through the table. Null-prototype as SIZE_ALIASES.
+const TONE_ALIASES: Record<string, string> = Object.assign(
+  Object.create(null) as Record<string, string>,
+  {
+    destructive: 'danger',
+    error: 'danger',
+    critical: 'danger',
+    negative: 'danger',
+    brand: 'primary',
+    positive: 'success',
+    notice: 'warning',
+    caution: 'warning',
+  } as const,
+);
+/** Every `@tone` spelling accepted, before narrowing. */
+export type PretuiToneArg =
+  | PretuiTone
+  | 'destructive'
+  | 'error'
+  | 'critical'
+  | 'negative'
+  | 'brand'
+  | 'positive'
+  | 'notice'
+  | 'caution';
+
+/** Narrow a tone to the subset a component paints; an unsupported tone falls back rather than emitting a data-tone no stylesheet matches. */
+export function resolveTone<T extends string>(
+  tone: string | undefined,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  if (!tone) {
+    return fallback;
+  }
+  let canonical = TONE_ALIASES[tone] ?? tone;
+  return (allowed as readonly string[]).includes(canonical)
+    ? (canonical as T)
+    : fallback;
+}
+
+/**
+ * Value-notify aliases for any control; `T` is what it emits. `@onChange` maps to
+ * the input event; blur semantics stay reachable with `{{on 'change'}}` through `...attributes`.
+ */
+export interface ControlNotifyArgs<T = string> {
+  onChange?: (value: T) => void;
+  onValueChange?: (value: T) => void;
+}
+
+/** The notify pair plus the boolean aliases a text-shaped control accepts; spread it only where all four booleans are wired. */
+export interface ControlAliasArgs<T = string> extends ControlNotifyArgs<T> {
+  /** alias of @disabled */
+  isDisabled?: boolean;
+  /** alias of @required */
+  isRequired?: boolean;
+  /** aliases of @readonly */
+  isReadOnly?: boolean;
+  readOnly?: boolean;
+}

package/bundled-realms/pretui/qrcode/LICENSE

@@ -0,0 +1,34 @@
+The MIT License (MIT)
+
+Copyright (c) 2012 Ryan Day
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+================================================================================
+Bundled dependency: dijkstrajs (MIT)
+================================================================================
+```
+Dijkstra path-finding functions. Adapted from the Dijkstar Python project.
+
+Copyright (C) 2008
+  Wyatt Baldwin <self@wyattbaldwin.com>
+  All rights reserved
+
+Licensed under the MIT license.
+
+  http://www.opensource.org/licenses/mit-license.php
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

package/bundled-realms/pretui/qrcode/README.md

@@ -0,0 +1,87 @@
+# qrcode/ — the `qrcode` encoder core, vendored
+
+`index.js` is the **encoder core** of
+[node-qrcode](https://github.com/soldair/node-qrcode) bundled to a single
+self-contained ES module. **21 KB min / 8.0 KB gzip.** Its one runtime
+dependency reached by this entry — `dijkstrajs`, used for segment-mode
+optimisation — is inlined; no bare specifier survives.
+
+## Provenance
+
+| | |
+|---|---|
+| **Source** | **npm registry** — `npm install qrcode@1.5.4` |
+| **Version** | `qrcode@1.5.4`, published release — so the version string alone identifies these bytes, and no commit SHA is needed |
+| **Bundled dep** | `dijkstrajs@1.0.3` |
+| **SPDX** | **MIT** (qrcode, Copyright (c) 2012 Ryan Day) and **MIT** (dijkstrajs, Copyright (C) 2008 Wyatt Baldwin) — both verified from the packages' own licence files |
+
+Both licences are concatenated verbatim into `LICENSE`.
+`--legal-comments=none` strips the notices out of the bundle, so the MIT notice
+clause is satisfied by that file plus the one-line banner at the top of
+`index.js`.
+
+A rebuild from a git checkout replaces this table with source / commit SHA /
+`git describe` / tree state; an untagged commit is identified only by its SHA,
+not by any published version.
+
+**This replaces a runtime CDN import.** The two prior in-tree implementations
+(`boxel-catalog/fields/qr-code/qr-code.gts` and the `catalog-source` copy) did
+`import QRCode from 'https://cdn.jsdelivr.net/npm/qrcode@1.5.4/+esm'` — a
+third-party network fetch on every module load, which breaks offline, pins us
+to jsDelivr's uptime, and is an unpinned supply-chain surface. Same library,
+same version, now resolved from the realm.
+
+## Exports
+
+    create(data, options) -> QRCodeSymbol
+
+That is the whole surface, deliberately:
+
+    { modules: BitMatrix, version, errorCorrectionLevel, maskPattern, segments }
+
+`options` accepts `errorCorrectionLevel` (`'L' | 'M' | 'Q' | 'H'`), `version`,
+`maskPattern`, `toSJISFunc`. `BitMatrix` is `{ size, data, get(row,col), … }`.
+
+Built with:
+
+    esbuild lean-qrcode.js --bundle --format=esm --minify --line-limit=500 \
+      --legal-comments=none --banner:js="<licence banner>" --outfile=index.js
+
+where `lean-qrcode.js` is `export { create } from '<pkg>/lib/core/qrcode.js';`
+
+## Why only the core, and not `qrcode/lib/browser.js`
+
+The upstream browser entry drags in the canvas renderer, the SVG-tag renderer,
+a promise shim and the arity-sniffing callback API — and both renderers bake a
+fixed colour and margin into a string we would immediately have to regex apart
+(the CDN version did exactly that: it string-replaced `width=`/`height=` out of
+the returned markup). Taking `create` instead gives us the module matrix and
+lets `qr-code.gts` emit **one `<svg>` with one `<path>`**, so the quiet zone
+lives in the `viewBox` where CSS cannot reach it, the accessible name is real
+markup, and no HTML is ever assembled from a string.
+
+## Three things to know before using it
+
+- **Import is DOM-free and so is `create()`.** Evaluating this module and
+  calling `create()` touch no DOM API (verified under plain Node). The bundle
+  contains **zero** `setTimeout` / `setInterval` / `requestAnimationFrame` /
+  `Date.now` / `Math.random` / `document.` / `window.` references — grep it.
+  That makes `create()` legal in a `@cached get`, which is why `QrCode` needs
+  no modifier at all.
+
+- **It throws on overflow.** Data longer than the chosen version + error
+  correction level can hold raises `The amount of data is too big to be stored
+  in a QR Code`. Callers must catch; `qr-code.gts` renders an error state.
+
+- **Empty string is not encodable** — `create('')` throws. Treat blank input as
+  "nothing to show", not as an error.
+
+## Reference vector
+
+`create('HELLO WORLD', { errorCorrectionLevel: 'Q', version: 1 })` reproduces
+the standard worked example (version 1, 21×21, mask pattern 6): three canonical
+finder patterns, the alternating timing row, and the dark module at
+`(4V + 9, 8)` set. The full 21×21 matrix is pinned as a golden fixture in
+`qr-code.test.gts` so a future rebuild of this bundle cannot drift silently.
+
+Consumer: `qr-code.gts`.