anentrypoint-design 0.0.477 → 0.0.480

package/README.md

@@ -29,6 +29,14 @@ npm install anentrypoint-design
 </script>
 ```
 
+`@latest` is unpinned — a production deploy tracking it silently picks up every future release, breaking or not, with no warning. Pin to the exact version you tested against instead:
+
+```html
+<script type="importmap">
+  { "imports": { "anentrypoint-design": "https://unpkg.com/anentrypoint-design@0.0.476/dist/247420.js" } }
+</script>
+```
+
 Add the scope class on a wrapping element and you are done:
 
 ```html
@@ -51,6 +59,72 @@ mount(document.getElementById('app'), () => C.AppShell({
 
 `mount` automatically adds `.ds-247420` to your root.
 
+## Framework integration
+
+The SDK is framework-free (webjsx + custom elements), so React/Vue integration
+means treating `<ds-chat>` (see below) as an imperative DOM element rather than
+a native component.
+
+**React** — set props/attributes on the element via `ref`, after import registers it:
+
+```jsx
+import { useRef, useEffect } from 'react';
+import 'anentrypoint-design'; // registers <ds-chat>
+
+function ChatWidget({ messages, onSend }) {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    el.messages = messages;
+    const handleSend = (e) => onSend(e.detail.text);
+    el.addEventListener('send', handleSend);
+    return () => el.removeEventListener('send', handleSend);
+  }, [messages, onSend]);
+
+  return <ds-chat ref={ref} />;
+}
+```
+
+**Vue** — tell the compiler `ds-chat` is a custom element (not a Vue component)
+so it isn't warned about / resolved against your component registry, then use
+it directly in a template. In `vite.config.js`:
+
+```js
+import vue from '@vitejs/plugin-vue';
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag === 'ds-chat',
+        },
+      },
+    }),
+  ],
+};
+```
+
+Then in a Vue SFC:
+
+```vue
+<script setup>
+import 'anentrypoint-design'; // registers <ds-chat>
+import { ref, onMounted } from 'vue';
+
+const el = ref(null);
+onMounted(() => {
+  el.value.messages = [{ role: 'assistant', text: 'gm.' }];
+  el.value.addEventListener('send', (e) => console.log(e.detail.text));
+});
+</script>
+
+<template>
+  <ds-chat ref="el" />
+</template>
+```
+
 ## what's in the box
 
 - **chrome** — `Topbar`, `Crumb`, `Side`, `Status`, `AppShell`, `Brand`, `Chip`, `Btn`, `Glyph`, `Heading`, `Lede`
@@ -257,6 +331,33 @@ Layout primitives worth knowing: `.ds-app-surface` is the Operate-mode page root
 
 The scanned set is computed, not listed: `COMPONENT_SHEETS` in `scripts/lint-tokens.mjs` names entry points and `expandSheets()` resolves each one's `@import` graph transitively, because the root `app-shell.css` is a barrel with no declarations of its own. A companion guard requires every `.css` file under `src/css/app-shell/` to appear in that expanded set, so a split sheet cannot be bundled into `dist/247420.css` while remaining invisible to both the linters and any consumer that `<link>`s `app-shell.css` directly.
 
+## Visual regression testing
+
+`npm run visual` (`node scripts/visual-baseline.mjs check`) screenshots every
+`preview/*.html` page (except `index.html`/`theme-map.html`) in three theme
+states — `paper`, `ink`, `auto` (with `auto` pinned to an emulated `light`
+color-scheme preference, so it captures deterministically) — via Chrome DevTools
+Protocol `Page.captureScreenshot` at a fixed 1280×900 viewport, then diffs each
+capture pixel-by-pixel against the matching committed PNG under
+`visual-baselines/`. It needs no browser-automation package and no image
+library: `scripts/cdp.mjs` drives an already-running Chrome over Node's built-in
+`WebSocket` (it never launches a browser itself — start one with
+`--headless --remote-debugging-port=9333`, or your own workflow step) and
+`scripts/png-diff.mjs` decodes PNG bytes using only `node:zlib`.
+
+A page fails the check when either: it has no committed baseline for a given
+file+theme combination, or its diff ratio exceeds `DIFF_THRESHOLD_RATIO`
+(0.5% of pixels), where a pixel only counts as differing once its per-channel
+delta exceeds `CHANNEL_TOLERANCE` (24/255) — this tolerance absorbs
+antialiasing/font-rendering jitter rather than flagging it as a regression. A
+size mismatch between capture and baseline is always a failure regardless of
+threshold.
+
+To (re-)freeze the current rendering as the new baseline, run
+`npm run visual:update` (`node scripts/visual-baseline.mjs update`), which
+overwrites every `visual-baselines/*.png` with a fresh capture — no diffing,
+no pass/fail, just a straight re-write.
+
 ## why scope-prefixed
 
 Every selector in the bundle is namespaced under `.ds-247420` via PostCSS. The bundle ships a system-font stack (`--ff-body`/`--ff-display`/`--ff-mono`, no web-font `@import`/`@font-face` -- see `colors_and_type.css`) + the design tokens **without** colliding with whatever the host app already runs. Add the class to a root element to opt in. The font tokens are fully overridable: set `--ff-body`/`--ff-display`/`--ff-mono` on any scope to swap typography without touching component code.

package/chat.css

@@ -567,7 +567,7 @@
   background: var(--bg); border: var(--border-w) solid var(--accent); border-radius: var(--r-1);
   padding: var(--space-1) var(--space-2);
 }
-.ds-session-rename-input:focus { outline: none; }
+.ds-session-rename-input:focus { outline: none; box-shadow: var(--focus-ring-inset); }
 
 /* Inline delete confirm — same row height, two flat buttons, no modal;
    mirrors SessionDashboard's arm-then-confirm bulk-stop control. */
@@ -1445,7 +1445,7 @@ button.chat-composer-context:focus-visible { outline: var(--focus-w) solid var(-
   /* Minimap internal order: centerline < viewport < dot < tooltip. All four
      live inside the one raised widget, so they share its rung and differ
      only by a local offset. */
-  z-index: calc(var(--z-raised) + 1);
+  z-index: var(--z-raised-1);
 }
 .chat-minimap-centerline {
   position: absolute;
@@ -1465,7 +1465,7 @@ button.chat-composer-context:focus-visible { outline: var(--focus-w) solid var(-
   border-radius: var(--r-pill, 999px);
   transform: translate(-50%, -50%) scale(1);
   transition: transform 0.1s;
-  z-index: calc(var(--z-raised) + 2);
+  z-index: var(--z-raised-2);
 }
 .chat-minimap-dot.is-user {
   background: color-mix(in oklab, var(--accent) 18%, transparent);
@@ -1490,7 +1490,7 @@ button.chat-composer-context:focus-visible { outline: var(--focus-w) solid var(-
   /* Top of the minimap's internal order. Deliberately NOT --z-tooltip: it is
      clipped to the minimap rail rather than floating over the app, so it must
      not outrank real overlays that may cover the rail. */
-  z-index: calc(var(--z-raised) + 3);
+  z-index: var(--z-raised-3);
   pointer-events: none;
   opacity: 0.45;
   font-size: var(--fs-tiny);

package/colors_and_type.css

@@ -201,12 +201,24 @@
   --fs-body:     16px;
   --fs-lg:       18px;
   --fs-xl:       21px;
-  --fs-h4:       clamp(22px, 2cqi, 26px);
+  --fs-h4:       clamp(24px, 2cqi, 28px);
   --fs-h3:       clamp(25px, 2.6cqi, 34px);
   --fs-h2:       clamp(28px, 3.6cqi, 44px);
   --fs-h1:       clamp(34px, 5cqi, 64px);
   --fs-hero:     clamp(42px, 7cqi, 96px);
   --fs-mega:     clamp(56px, 11cqi, 168px);
+  /* Bridges the fixed --fs-* ladder (tops out at --fs-xl, 21px) and the fluid
+     heading clamps below it — use for fixed (non-clamping) UI text that needs
+     to sit between --fs-xl and a heading tier, e.g. empty-state icon glyphs. */
+  --fs-2xl:      28px;
+
+  /* Icon size scale — canonical sizes for glyphs/icons across the kit going
+     forward. Existing ad-hoc pixel values (6/7/8/10/12/14/16/18px etc.)
+     don't need to be migrated in this pass; new/updated icon usage should. */
+  --icon-xs: 12px;
+  --icon-sm: 16px;
+  --icon-md: 20px;
+  --icon-lg: 24px;
 
   /* App/chrome typescale: the default heading scale above is tuned for
      marketing/hero layouts (h1 up to 64px). Application chrome — page titles,
@@ -355,6 +367,9 @@
   --z-below:      -1;
   --z-base:        0;
   --z-raised:    100;
+  --z-raised-1:  calc(var(--z-raised) + 1);
+  --z-raised-2:  calc(var(--z-raised) + 2);
+  --z-raised-3:  calc(var(--z-raised) + 3);
   --z-sticky:    200;
   --z-header:    300;
   --z-drawer:    400;
@@ -415,6 +430,9 @@
   --focus-w:           2px;
   --focus-offset:      2px;
   --focus-ring-inset:  inset 0 0 0 var(--focus-w) var(--focus-color);
+
+  /* letterbox background for video/media containers */
+  --media-letterbox:   #000;
 }
 
 /* ============================================================
@@ -716,8 +734,20 @@ select:focus-visible {
 
 /* Type-scale modifier — opt-in body/lg/xl bump for surfaces that want denser
    or larger reading sizes without a custom override. */
-[data-typescale="sm"] { --fs-body: 15px; --fs-lg: 17px; --fs-xl: 20px; }
-[data-typescale="lg"] { --fs-body: 17px; --fs-lg: 20px; --fs-xl: 24px; }
+[data-typescale="sm"] {
+  --fs-body: 15px; --fs-lg: 17px; --fs-xl: 20px;
+  --fs-h4: clamp(22px, 1.9cqi, 24px);
+  --fs-h3: clamp(23px, 2.4cqi, 32px);
+  --fs-h2: clamp(26px, 3.4cqi, 41px);
+  --fs-h1: clamp(32px, 4.7cqi, 60px);
+}
+[data-typescale="lg"] {
+  --fs-body: 17px; --fs-lg: 20px; --fs-xl: 24px;
+  --fs-h4: clamp(27px, 2.2cqi, 31px);
+  --fs-h3: clamp(28px, 2.9cqi, 38px);
+  --fs-h2: clamp(31px, 4cqi, 49px);
+  --fs-h1: clamp(38px, 5.6cqi, 71px);
+}
 
 /* Debug grid overlay — 8px mascot grid. Toggle via class on any container. */
 .with-grid-overlay {

package/community.css

@@ -132,6 +132,9 @@
   min-width: 18px;
   height: 18px;
   padding: 0 var(--space-1-5);
+  /* TODO(a11y): --paper is a fixed near-white on --warn (#FF5A52) -- likely
+     ~3:1, below the 4.5:1 AA floor (same defect fixed via --ink elsewhere
+     for --warn text). Small numeric badge; needs contrast audit. */
   background: var(--warn);
   color: var(--paper);
   font-family: var(--ff-mono);
@@ -464,6 +467,9 @@
   min-width: 16px;
   height: 16px;
   padding: 0 var(--space-1-5);
+  /* TODO(a11y): --paper is a fixed near-white on --warn (#FF5A52) -- likely
+     ~3:1, below the 4.5:1 AA floor (same defect fixed via --ink elsewhere
+     for --warn text). Small numeric badge; needs contrast audit. */
   background: var(--warn);
   color: var(--paper);
   font-family: var(--ff-mono);
@@ -547,7 +553,7 @@
   height: 20px;
   border-radius: 50%;
   background: var(--avatar-bg, var(--bg-3));
-  color: var(--fg-2);
+  color: var(--avatar-fg, var(--fg-2));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -653,8 +659,11 @@
   background: color-mix(in oklab, var(--fg) 18%, transparent);
 }
 .cm-vs-btn.danger {
+  /* --ink, not --paper: --paper is a fixed near-white, which measures ~3:1 on
+     --warn (#FF5A52) -- below the 4.5:1 AA floor. Same fix pattern as
+     .btn-primary.danger in app-shell/files.css. */
   background: var(--warn);
-  color: var(--paper);
+  color: var(--ink);
 }
 .cm-vs-btn.danger:hover {
   background: color-mix(in oklab, var(--warn) 80%, var(--ink));
@@ -679,7 +688,7 @@
   height: 32px;
   border-radius: 50%;
   background: var(--avatar-bg, var(--bg-3));
-  color: var(--fg-2);
+  color: var(--avatar-fg, var(--fg-2));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -890,7 +899,7 @@
   height: 28px;
   border-radius: 50%;
   background: var(--avatar-bg, var(--bg-3));
-  color: var(--fg-2);
+  color: var(--avatar-fg, var(--fg-2));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -951,7 +960,7 @@
   height: 56px;
   border-radius: 50%;
   background: var(--avatar-bg, var(--bg-3));
-  color: var(--fg-2);
+  color: var(--avatar-fg, var(--fg-2));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -1664,10 +1673,14 @@
 /* PageView — cm-page / cm-page-* */
 .cm-page { display: flex; flex-direction: column; height: 100%; min-height: 0; overflow-y: auto; background: var(--bg-1, var(--bg-2)); color: var(--fg); }
 .cm-page-head { display: flex; align-items: center; justify-content: space-between; gap: var(--space-2); padding: var(--space-3); border-bottom: var(--bw-hair) solid var(--rule); }
+.cm-page-head-title { display: flex; flex-direction: column; gap: var(--space-1); min-width: 0; }
 .cm-page-title { margin: 0; font-size: var(--fs-xl); font-weight: 700; }
+.cm-page-meta { display: flex; align-items: center; gap: var(--space-2); font-size: var(--fs-xs); color: var(--fg-2, var(--fg)); }
+.cm-page-author { font-weight: 500; }
+.cm-page-time { opacity: .75; }
 .cm-page-edit { padding: var(--space-1) var(--space-2); border: var(--bw-hair) solid var(--rule-strong); border-radius: var(--r-1); background: var(--bg-3); color: var(--fg); cursor: pointer; }
 .cm-page-body { padding: var(--space-3); line-height: 1.6; }
-.cm-page-empty { color: var(--fg-2, var(--fg)); opacity: .7; }
+.cm-page-empty { color: var(--fg-2, var(--fg)); opacity: .82; }
 
 /* ============================================================
    freddie pages — layout for FREDDIE_PAGES renderers.
@@ -1680,8 +1693,9 @@
 .fd-empty { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: var(--space-2, 10px); padding: var(--space-5, 32px) var(--space-3, 16px); color: var(--fg-2, var(--fg)); text-align: center; }
 /* 28px is an ICON size (empty-state mark), not a type tier — the --fs-* ladder
    tops out at --fs-xl (21px) before every remaining rung becomes a fluid
-   heading clamp, so neither substitutes without visibly resizing the mark. */
-.fd-empty-glyph { font-size: 28px; opacity: .55; line-height: 1; }
+   heading clamp, so neither substitutes without visibly resizing the mark.
+   --fs-2xl bridges that gap as a fixed 28px token. */
+.fd-empty-glyph { font-size: var(--fs-2xl); opacity: .55; line-height: 1; }
 .fd-pre { margin: 0; padding: var(--space-2, 10px); background: var(--bg-3, var(--panel-bg-2)); border: var(--bw-hair, 1px) solid var(--rule, var(--panel-accent)); border-radius: var(--r-1, 6px); overflow: auto; max-height: 460px; white-space: pre-wrap; overflow-wrap: anywhere; word-break: break-word; font-family: var(--font-mono, ui-monospace, monospace); font-size: var(--fs-micro); line-height: 1.5; }
 .fd-skill-body { max-height: 320px; }
 .fd-row-actions { display: inline-flex; gap: var(--space-1, 6px); align-items: center; }