@tjakoen/grain 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/LICENSE +202 -0
  2. package/PLAN.md +27 -0
  3. package/README.md +243 -0
  4. package/ai/accepts.test.ts +69 -0
  5. package/ai/accepts.ts +57 -0
  6. package/ai/ai.css +127 -0
  7. package/ai/client-door.test.ts +70 -0
  8. package/ai/client-door.ts +56 -0
  9. package/ai/contract.test.ts +158 -0
  10. package/ai/contract.ts +285 -0
  11. package/ai/interaction-layer.test.ts +270 -0
  12. package/ai/interaction-layer.ts +138 -0
  13. package/ai/manifest-dom.test.ts +176 -0
  14. package/ai/manifest-dom.ts +187 -0
  15. package/ai/manifest.test.ts +71 -0
  16. package/ai/manifest.ts +57 -0
  17. package/ai/markdown.test.ts +68 -0
  18. package/ai/markdown.ts +74 -0
  19. package/ai/model-chat.test.ts +131 -0
  20. package/ai/model-chat.ts +151 -0
  21. package/ai/model-reasoner.test.ts +152 -0
  22. package/ai/model-reasoner.ts +146 -0
  23. package/ai/model.test.ts +148 -0
  24. package/ai/model.ts +200 -0
  25. package/ai/reasoner-kit.test.ts +142 -0
  26. package/ai/reasoner-kit.ts +159 -0
  27. package/ai/reasoner.test.ts +227 -0
  28. package/ai/reasoner.ts +446 -0
  29. package/ai/timeline-log.test.ts +55 -0
  30. package/ai/timeline-log.ts +50 -0
  31. package/ai/vocab-reference.test.ts +43 -0
  32. package/ai/vocab-reference.ts +107 -0
  33. package/ai/webllm.test.ts +79 -0
  34. package/ai/webllm.ts +125 -0
  35. package/assets/figure-sample.svg +14 -0
  36. package/assets/sprite.svg +22 -0
  37. package/catalog/catalog.test.ts +37 -0
  38. package/catalog/catalog.ts +424 -0
  39. package/components/atoms/action-badge/action-badge.css +17 -0
  40. package/components/atoms/action-badge/action-badge.html +6 -0
  41. package/components/atoms/action-badge/action-badge.md +23 -0
  42. package/components/atoms/b-badge/b-badge.css +15 -0
  43. package/components/atoms/b-badge/b-badge.html +2 -0
  44. package/components/atoms/b-badge/b-badge.md +16 -0
  45. package/components/atoms/b-button/b-button.ai.md +22 -0
  46. package/components/atoms/b-button/b-button.css +87 -0
  47. package/components/atoms/b-button/b-button.html +5 -0
  48. package/components/atoms/b-button/b-button.md +77 -0
  49. package/components/atoms/b-icon/b-icon.css +10 -0
  50. package/components/atoms/b-icon/b-icon.html +5 -0
  51. package/components/atoms/b-icon/b-icon.md +36 -0
  52. package/components/atoms/b-icon-button/b-icon-button.ai.md +11 -0
  53. package/components/atoms/b-icon-button/b-icon-button.css +43 -0
  54. package/components/atoms/b-icon-button/b-icon-button.html +8 -0
  55. package/components/atoms/b-icon-button/b-icon-button.md +33 -0
  56. package/components/atoms/b-input/b-input.css +36 -0
  57. package/components/atoms/b-input/b-input.html +8 -0
  58. package/components/atoms/b-input/b-input.md +59 -0
  59. package/components/atoms/b-kbd/b-kbd.css +11 -0
  60. package/components/atoms/b-kbd/b-kbd.html +3 -0
  61. package/components/atoms/b-kbd/b-kbd.md +13 -0
  62. package/components/atoms/b-list/b-list.css +21 -0
  63. package/components/atoms/b-list/b-list.html +6 -0
  64. package/components/atoms/b-list/b-list.md +24 -0
  65. package/components/atoms/b-meter/b-meter.css +39 -0
  66. package/components/atoms/b-meter/b-meter.md +44 -0
  67. package/components/atoms/b-select/b-select.css +35 -0
  68. package/components/atoms/b-select/b-select.md +75 -0
  69. package/components/atoms/b-switch/b-switch.css +61 -0
  70. package/components/atoms/b-switch/b-switch.html +6 -0
  71. package/components/atoms/b-switch/b-switch.md +40 -0
  72. package/components/atoms/b-text/b-text.ai.md +29 -0
  73. package/components/atoms/b-text/b-text.css +2 -0
  74. package/components/atoms/b-text/b-text.html +3 -0
  75. package/components/atoms/b-text/b-text.md +23 -0
  76. package/components/atoms/code-block/code-block.css +42 -0
  77. package/components/atoms/code-block/code-block.md +23 -0
  78. package/components/examples.test.ts +23 -0
  79. package/components/molecules/callout/callout.css +19 -0
  80. package/components/molecules/callout/callout.md +15 -0
  81. package/components/molecules/card/card.css +28 -0
  82. package/components/molecules/card/card.md +30 -0
  83. package/components/molecules/chat-message/chat-message.css +83 -0
  84. package/components/molecules/chat-message/chat-message.md +52 -0
  85. package/components/molecules/chip-group/chip-group.css +35 -0
  86. package/components/molecules/chip-group/chip-group.md +42 -0
  87. package/components/molecules/content-index/content-index.css +87 -0
  88. package/components/molecules/content-index/content-index.md +27 -0
  89. package/components/molecules/content-source/content-source.css +6 -0
  90. package/components/molecules/content-source/content-source.md +13 -0
  91. package/components/molecules/figure/figure.css +19 -0
  92. package/components/molecules/figure/figure.md +20 -0
  93. package/components/molecules/lede/lede.css +17 -0
  94. package/components/molecules/lede/lede.md +17 -0
  95. package/components/molecules/made-with/made-with.css +25 -0
  96. package/components/molecules/made-with/made-with.md +35 -0
  97. package/components/molecules/nav-item/nav-item.css +19 -0
  98. package/components/molecules/nav-item/nav-item.md +21 -0
  99. package/components/molecules/stat-tile/stat-tile.css +34 -0
  100. package/components/molecules/stat-tile/stat-tile.md +50 -0
  101. package/components/molecules/status-list/status-list.css +47 -0
  102. package/components/molecules/status-list/status-list.md +62 -0
  103. package/components/molecules/tab/tab.css +32 -0
  104. package/components/molecules/tab/tab.md +27 -0
  105. package/components/molecules/table/table.css +23 -0
  106. package/components/molecules/table/table.md +18 -0
  107. package/components/organisms/activity-bar/activity-bar.css +36 -0
  108. package/components/organisms/activity-bar/activity-bar.md +43 -0
  109. package/components/organisms/app-shell/app-shell.css +193 -0
  110. package/components/organisms/app-shell/app-shell.md +58 -0
  111. package/components/organisms/app-shell/app-shell.test.ts +74 -0
  112. package/components/organisms/app-window/app-window.css +111 -0
  113. package/components/organisms/app-window/app-window.md +53 -0
  114. package/components/organisms/chat-log/chat-log.css +5 -0
  115. package/components/organisms/chat-log/chat-log.md +14 -0
  116. package/components/organisms/code-editor/code-editor.ai.md +31 -0
  117. package/components/organisms/code-editor/code-editor.css +111 -0
  118. package/components/organisms/code-editor/code-editor.md +122 -0
  119. package/components/organisms/console/console.css +112 -0
  120. package/components/organisms/console/console.md +66 -0
  121. package/components/organisms/file-tree/file-tree.css +85 -0
  122. package/components/organisms/file-tree/file-tree.md +49 -0
  123. package/components/organisms/note/note.css +19 -0
  124. package/components/organisms/note/note.md +20 -0
  125. package/components/organisms/notepad/notepad.css +60 -0
  126. package/components/organisms/notepad/notepad.md +40 -0
  127. package/components/organisms/side-rail/side-rail.css +55 -0
  128. package/components/organisms/side-rail/side-rail.md +24 -0
  129. package/components/organisms/sidebar-panel/sidebar-panel.css +69 -0
  130. package/components/organisms/sidebar-panel/sidebar-panel.md +47 -0
  131. package/components/organisms/status-bar/status-bar.css +33 -0
  132. package/components/organisms/status-bar/status-bar.md +28 -0
  133. package/components/organisms/tab-bar/tab-bar.css +48 -0
  134. package/components/organisms/tab-bar/tab-bar.md +26 -0
  135. package/components/organisms/timeline/timeline.css +51 -0
  136. package/components/organisms/timeline/timeline.md +42 -0
  137. package/components/organisms/topbar/topbar.css +8 -0
  138. package/components/organisms/topbar/topbar.md +26 -0
  139. package/components/responsive-polish.test.ts +43 -0
  140. package/components/tokens.test.ts +39 -0
  141. package/fonts/redaction-35-400.woff2 +0 -0
  142. package/fonts/redaction-400.woff2 +0 -0
  143. package/fonts/redaction-50-400.woff2 +0 -0
  144. package/fonts/redaction-70-400.woff2 +0 -0
  145. package/package.json +46 -0
  146. package/scripts/ai-dispatch.js +583 -0
  147. package/scripts/ai-dispatch.test.ts +85 -0
  148. package/scripts/ai-spotlight.d.ts +23 -0
  149. package/scripts/ai-spotlight.js +139 -0
  150. package/scripts/ai-spotlight.test.ts +31 -0
  151. package/scripts/catalog-peek.js +156 -0
  152. package/scripts/catalog-peek.test.ts +31 -0
  153. package/scripts/cmdk.js +159 -0
  154. package/scripts/demo-box.js +53 -0
  155. package/scripts/handoff.js +64 -0
  156. package/scripts/handoff.test.ts +36 -0
  157. package/scripts/lightbox.js +144 -0
  158. package/scripts/lightbox.test.ts +23 -0
  159. package/scripts/made-with.d.ts +2 -0
  160. package/scripts/made-with.js +22 -0
  161. package/scripts/made-with.test.ts +25 -0
  162. package/scripts/notepad.js +100 -0
  163. package/scripts/shell.js +204 -0
  164. package/scripts/shell.test.ts +50 -0
  165. package/scripts/tabs.js +127 -0
  166. package/scripts/tabs.test.ts +40 -0
  167. package/scripts/terminal.js +271 -0
  168. package/scripts/terminal.test.ts +36 -0
  169. package/scripts/theme-boot.js +15 -0
  170. package/scripts/theme.js +87 -0
  171. package/scripts/type-effect.js +25 -0
  172. package/scripts/xray.js +79 -0
  173. package/scripts/xray.test.ts +43 -0
  174. package/styles/cmdk.css +65 -0
  175. package/styles/global.css +80 -0
  176. package/styles/grain.css +47 -0
  177. package/styles/lightbox.css +78 -0
  178. package/styles/themes/_template.css +48 -0
  179. package/styles/themes/baguette.css +30 -0
  180. package/styles/themes/brioche.css +30 -0
  181. package/styles/variables.css +217 -0
@@ -0,0 +1,36 @@
1
+ /* organisms/activity-bar — the VS Code ACTIVITY BAR: a slim vertical icon column at the far edge
2
+ of the app-shell rail. Icon-only entries (an explorer toggle, app links); the consumer supplies
3
+ the links + glyphs (persona-neutral, tokens only). Mounts as the FIRST child of
4
+ `.app-shell__rail`, sibling of a nested `.side-rail` — it does NOT add a grid column (see the
5
+ rejected alternative in activity-bar.md); it rides the rail's existing track + mobile drawer. */
6
+ .activity-bar {
7
+ flex: 0 0 auto;
8
+ display: flex; flex-direction: column; align-items: center; gap: var(--space-1);
9
+ width: 3.25rem; /* matches the collapsed-rail track */
10
+ padding: var(--space-2) 0;
11
+ border-right: 1px solid color-mix(in srgb, var(--color-line) 55%, transparent);
12
+ }
13
+ /* ≥44px touch target (DESIGN-SYSTEM §7 — the same promise b-icon-button makes; this is a bespoke
14
+ square, not a composed .icon-btn, so it has to hold the floor itself). Was 2.25rem/36px until
15
+ the 2026-07-14 responsive-polish audit flagged the rail-toggle path as untappable on mobile; the
16
+ 3.25rem column still centers a 2.75rem item with 4px to spare on each side. flex-shrink:0 for the
17
+ same reason b-icon-button carries it now — a squeezed rail column must never shrink the target. */
18
+ .activity-bar__item {
19
+ display: flex; align-items: center; justify-content: center; flex-shrink: 0;
20
+ width: 2.75rem; height: 2.75rem; border-radius: var(--radius-sm);
21
+ position: relative;
22
+ color: var(--color-muted); background: transparent; border: 0; cursor: pointer;
23
+ text-decoration: none;
24
+ }
25
+ .activity-bar__item:hover { color: var(--color-fg); }
26
+ /* the CURRENT item: ink + a 2px accent left edge (mirrors the file-tree's open-file bar) */
27
+ .activity-bar__item[aria-current="true"], .activity-bar__item[aria-current="page"] { color: var(--color-fg); }
28
+ .activity-bar__item[aria-current="true"]::before, .activity-bar__item[aria-current="page"]::before {
29
+ content: ""; position: absolute; top: 0.35rem; bottom: 0.35rem; left: -2px;
30
+ width: 2px; background: var(--color-accent);
31
+ }
32
+ .activity-bar__spacer { flex: 1 1 auto; }
33
+
34
+ /* NB: the app-shell OPT-IN rule (`.app-shell__rail:has(> .activity-bar)` becomes a flex row) lives
35
+ in app-shell.css — the SAME sheet as the mobile-drawer rules, so bundle order can't let the
36
+ drawer's `position: fixed` lose to this. See activity-bar.md + app-shell.css. */
@@ -0,0 +1,43 @@
1
+ # activity-bar
2
+
3
+ The VS Code **activity bar**: a slim vertical icon column at the far edge of the app-shell rail.
4
+ Icon-only entries — an explorer toggle at the top, app links (with a `.activity-bar__spacer` to push
5
+ some to the bottom). Persona-neutral and CSS-only: the consumer supplies the links, hrefs, and
6
+ glyphs. A layout class composed of native `<a>`/`<button>` + `b-icon`, not a data-bound tag.
7
+
8
+ Entries are plain links (`.activity-bar__item`) — no panel-switching JS. Each MUST carry an
9
+ `aria-label` + `title` (icon-only, so the text label is the accessible name). Mark the current
10
+ section's item `aria-current="true"` (or `"page"`) for the accent left-edge.
11
+
12
+ ## Parent context (state it here — lesson 3)
13
+
14
+ - Mounts as the **first child of `.app-shell__rail`** (or of `.rail-body`, if the rail also carries
15
+ a `.rail-head`), sibling of a nested `.side-rail`. The container opts into a flex row
16
+ automatically: `:has(> .activity-bar)` (app-shell.css). A rail without an activity-bar is
17
+ unaffected — the `:has()` rule simply never matches.
18
+ - **Collapse:** `[data-rail-collapsed="true"]` hides the `.side-rail` (the tree) and leaves only the
19
+ icon strip — the VS Code "collapsed to icons" look. Falls out of the existing collapse attribute;
20
+ no new JS.
21
+ - **Mobile:** it's part of the rail, so it rides the off-canvas drawer for free (the drawer is
22
+ `position: fixed` on `.app-shell__rail`). Nothing special.
23
+
24
+ ```html
25
+ <aside class="app-shell__rail" data-tab-source>
26
+ <nav class="activity-bar" aria-label="Activity">
27
+ <button class="activity-bar__item" data-shell="rail-toggle" aria-current="true"
28
+ title="Explorer" aria-label="Explorer"><b-icon sym="/assets/sprite.svg#files"></b-icon></button>
29
+ <span class="activity-bar__spacer"></span>
30
+ <a class="activity-bar__item" href="/calendar" data-section="calendar" data-tab-label="Calendar"
31
+ title="Calendar" aria-label="Calendar"><b-icon sym="/assets/sprite.svg#traces"></b-icon></a>
32
+ </nav>
33
+ <div class="side-rail" data-variant="explorer"> …brand + file-tree… </div>
34
+ </aside>
35
+ ```
36
+
37
+ ## Rejected alternative (why not a 4th grid column)
38
+
39
+ The activity bar could have been its own `grid-template-columns` track on `.app-shell`. Rejected: the
40
+ mobile drawer is `position: fixed` on `.app-shell__rail` — an in-rail strip rides that drawer for
41
+ free, whereas a separate column would need its own drawer plumbing. Keeping it in-rail also keeps
42
+ `data-tab-source` singular (tabs.js takes the first match) and lets the existing collapse attribute
43
+ do the icon-strip fold. The cost is one `:has()` opt-in rule in app-shell.css — cheap and contained.
@@ -0,0 +1,193 @@
1
+ /* organisms/app-shell — the WORKSPACE layout (the "work-y" archetype): a full-viewport
2
+ grid of five regions — a left rail, a top bar, the main pane, a right aside (the
3
+ assistant), and a bottom console. It HOSTS arbitrary page content, so it's a layout
4
+ the page applies via region classes (the render engine can't project children into a
5
+ component), not a data-bound tag. Re-skins via tokens like everything else. Coexists
6
+ with the single-column editorial `.container`; the reference app composes it via portfolio-frame
7
+ (tjakoen.github.io/components/organisms/portfolio-frame) on every page, incl. /loop. */
8
+
9
+ /* Two optional full-width rows bracket the workspace: "window" (the app-window title bar)
10
+ and "status" (the status-bar). Auto rows collapse to zero when a page places nothing in
11
+ them, so shells without the editor-window dressing are untouched. The ASIDE (assistant)
12
+ spans the full right column from the topbar row down — it sits beside the tab bar, not
13
+ under it (no dead space). The CONSOLE (terminal) docks under main only, as a bottom panel. */
14
+ .app-shell {
15
+ display: grid;
16
+ height: 100dvh;
17
+ grid-template-columns: var(--shell-rail, 15rem) minmax(0, 1fr) var(--shell-aside, 20rem);
18
+ /* main + console rows are minmax tracks whose endpoints are ALL lengths/fr — never `auto` or
19
+ `min-content` — so grid-template-rows stays INTERPOLABLE and every console state change
20
+ (closed→open band→full-screen) GLIDES instead of snapping (an auto/px↔fr endpoint makes the
21
+ whole track list discrete → an instant jump; measured). The console height is driven entirely
22
+ by the track here, not by the feed's content: `--shell-console-min` is the floor (bar height
23
+ when closed, a band when open) and `--shell-console-fr` grows it to fill on expand. The feed
24
+ is `flex:1 1 0` (console.css) so it has zero intrinsic height and simply fills whatever the
25
+ track gives — which is what lets the floor be an exact length with no content-balloon. */
26
+ grid-template-rows: auto auto minmax(0, var(--shell-main-fr, 1fr)) minmax(var(--shell-console-min, 2.75rem), var(--shell-console-fr, 0fr)) auto;
27
+ grid-template-areas:
28
+ "window window window"
29
+ "rail topbar aside"
30
+ "rail main aside"
31
+ "rail console aside"
32
+ "status status status";
33
+ background: var(--color-bg);
34
+ color: var(--color-fg);
35
+ overflow: hidden;
36
+ /* panels glide in/out: the rail/aside columns animate their width (grid tracks interpolate);
37
+ main/console share the SAME transition when the console grows (see data-console-expanded). */
38
+ transition: grid-template-columns 0.26s ease, grid-template-rows 0.26s ease;
39
+ }
40
+ .app-shell[data-rail-collapsed="true"] { --shell-rail: 3.25rem; } /* icons-only rail */
41
+ /* OPEN: the console grows from the slim bar to a docked BAND — the floor rises from the bar
42
+ height to ~16rem. A length↔length change, so it glides (grid-rows transition above). NOTE:
43
+ `data-acting` (a run) does NOT open the band — during a run the terminal stays collapsed and the
44
+ CHAT previews the output; the person clicks "open in terminal" (→ data-console-open) to expand
45
+ it (loop.e2e "takeover"). */
46
+ .app-shell[data-console-open] { --shell-console-min: 16rem; }
47
+ /* GROWN (console.css's `console__grow` toggle): the console takes over the WHOLE screen — main's
48
+ fr goes to 0 (`minmax(0, 0fr)` collapses it) and the console's fr goes to 1 so it fills the
49
+ freed space. Only the fr coefficients change against a fixed floor, so it glides both ways
50
+ (measured: a smooth main-height ramp to 0, not a snap). */
51
+ .app-shell[data-console-expanded] { --shell-main-fr: 0fr; --shell-console-fr: 1fr; }
52
+
53
+ /* ---- OPT-IN: a `.rail-head` (full-width, brand/title row) stacks the rail vertically — the
54
+ head sits at the SAME height as the topbar row beside it, and everything below it (the icon
55
+ column + tree) starts on its own line underneath. A rail without one is untouched (flex-column
56
+ with a single child behaves like the old block layout). ---- */
57
+ .app-shell__rail:has(> .rail-head) { display: flex; flex-direction: column; }
58
+ .app-shell__rail > .rail-body { min-height: 0; }
59
+ .app-shell__rail:has(> .rail-head) > .rail-body { flex: 1 1 auto; }
60
+
61
+ /* ---- OPT-IN: a rail hosting an `activity-bar` (VS Code icon column) becomes a flex row — the
62
+ strip beside the tree. Composes with `.rail-head` above (activity-bar sits in `.rail-body` then)
63
+ or stands alone as a direct child of `__rail`. A rail with NEITHER is untouched (these `:has()`
64
+ rules never match). This rule lives HERE, alongside the mobile-drawer rules below, so bundle
65
+ order can never let the drawer's `position: fixed` lose to it (the same trap that once broke the
66
+ drawer — see the mobile block). Collapsed rail = the icon strip only (the tree hides, the
67
+ activity bar stays). ---- */
68
+ .app-shell__rail:has(> .activity-bar), .app-shell__rail > .rail-body:has(> .activity-bar) {
69
+ display: flex; flex-direction: row; align-items: stretch;
70
+ }
71
+ .app-shell__rail:has(> .activity-bar) > .side-rail,
72
+ .app-shell__rail > .rail-body:has(> .activity-bar) > .side-rail { flex: 1 1 auto; min-width: 0; }
73
+ .app-shell[data-rail-collapsed="true"] .app-shell__rail:has(> .activity-bar) > .side-rail,
74
+ .app-shell[data-rail-collapsed="true"] .app-shell__rail > .rail-body:has(> .activity-bar) > .side-rail { display: none; }
75
+
76
+ /* VS Code-style pane visibility (shell.js: data-shell="aside-toggle"). The aside animates to width
77
+ 0 (no display:none, so the glide is smooth); its border/scroll fold away at zero. */
78
+ .app-shell[data-aside-hidden="true"] { --shell-aside: 0rem; }
79
+ .app-shell[data-aside-hidden="true"] .app-shell__aside { border-left: 0; overflow: hidden; }
80
+ .app-shell[data-console-hidden="true"] .app-shell__console { display: none; }
81
+ @media (prefers-reduced-motion: reduce) { .app-shell { transition: none; } }
82
+
83
+ /* ---- the regions (grid slots) ---- */
84
+ .app-shell__window { grid-area: window; min-width: 0; }
85
+ .app-shell__status { grid-area: status; min-width: 0; }
86
+ /* the rail separates from the content with a SOFTENED hairline — present, but quieter than
87
+ the rail's own icon-gutter line, so the eye reads gutter > rail-edge as two weights. */
88
+ .app-shell__rail { grid-area: rail; min-height: 0;
89
+ border-right: 1px solid color-mix(in srgb, var(--color-line) 55%, transparent); }
90
+ /* position:relative + a real z-index (not "auto") pins the topbar — and the rail-toggle hamburger
91
+ inside it — above anything else painting in this stacking context; explicit pointer-events:auto
92
+ guards against ever inheriting a stray `none` from an ancestor. Defensive: the 2026-07-14 audit
93
+ found the mobile hamburger timing out in Playwright (present, but unclickable) at squeezed
94
+ widths — the root cause was the grid-squeeze the @container fix above resolves, but a control
95
+ this load-bearing (it's the ONLY way to reach the rail on mobile) shouldn't also depend on
96
+ nothing else ever drifting a z-index/pointer-events value over it. */
97
+ .app-shell__topbar { grid-area: topbar; min-width: 0; display: flex; align-items: stretch;
98
+ min-height: var(--editor-header-h, 2.9rem); /* aligns with the panel head (one line) */
99
+ border-bottom: 1px solid var(--color-line); background: var(--color-surface);
100
+ position: relative; z-index: 1; pointer-events: auto; }
101
+ /* __main owns the page scroll inside the shell — it must OPT INTO the smooth-scroll contract
102
+ (global.css sets it on html, but scrollIntoView scrolls the nearest scrollable ancestor,
103
+ which in a shell is this pane; without it the AI's focus jumps are instant). */
104
+ .app-shell__main { grid-area: main; min-width: 0; overflow: auto; scroll-behavior: smooth; }
105
+ @media (prefers-reduced-motion: reduce) { .app-shell__main { scroll-behavior: auto; } }
106
+ .app-shell__aside { grid-area: aside; min-height: 0; overflow: auto;
107
+ border-left: 1px solid var(--color-line); background: var(--color-surface); }
108
+ .app-shell__console { grid-area: console; border-top: 1px solid var(--color-line);
109
+ background: var(--color-bg); }
110
+ .app-shell__scrim { display: none; } /* only used as the drawer scrim on mobile */
111
+
112
+ /* ---- CONTAINER (2026-07-14 responsive-polish fix): the two layout breakpoints below used to be
113
+ `@media`, which reads the actual BROWSER viewport — so the viewport-toggle's cosmetic max-width
114
+ clamp on `.app-shell` (see the bottom of this file) never made them fire; a squeezed real window
115
+ between 768-1100px also just squeezed the fixed rail/aside tracks instead of collapsing (the
116
+ `minmax(0,1fr)` main column went to zero, not the layout).
117
+
118
+ Fix: `.app-shell` cannot query an `@container` condition on ITSELF (the CSS containment spec:
119
+ a container never matches its own query, only its descendants' do) — so the container has to be
120
+ an ANCESTOR. `.app-shell` has no wrapper of its own in any real composition (portfolio-frame,
121
+ this file's own .md demo): it is always a DIRECT CHILD of `<body>`. So `<body>` becomes the named
122
+ container (`shell-frame`), scoped with `:has()` so a page with no shell is untouched. Both
123
+ `.app-shell` and its descendants (`.app-shell__aside`, `sidebar-panel`, `status-bar`) can then
124
+ legally query it. The viewport-toggle's clamp moves to `body[data-viewport]` too (below) — so
125
+ shrinking body for the toggle shrinks the SAME container real narrow windows shrink, and both
126
+ paths now drive the identical mobile layout. `container-type: inline-size` only tracks/queries
127
+ the inline axis, which is exactly the width-based breakpoints below — height stays content-sized
128
+ as before (100dvh via .app-shell, unaffected). */
129
+ body:has(.app-shell) { container-type: inline-size; container-name: shell-frame; }
130
+
131
+ /* ---- narrow desktop: keep all three columns but tighten the aside so the assistant
132
+ stays reachable (dropping it here stranded the chat on laptop-width windows) ---- */
133
+ @container shell-frame (max-width: 1100px) {
134
+ .app-shell { --shell-aside: 16rem; }
135
+ }
136
+
137
+ /* ---- mobile: single column; the rail becomes an off-canvas drawer. The aside (assistant)
138
+ becomes a bottom sheet (sidebar-panel.css, which loads after this file and wins the tie). ---- */
139
+ @container shell-frame (max-width: 768px) {
140
+ .app-shell {
141
+ grid-template-columns: minmax(0, 1fr);
142
+ grid-template-areas: "window" "topbar" "main" "console" "status";
143
+ grid-template-rows: auto auto minmax(0, 1fr) auto auto;
144
+ }
145
+ .app-shell__aside { display: none; }
146
+ .app-shell[data-rail-collapsed="true"] { --shell-rail: 15rem; } /* collapse-width is desktop-only */
147
+ /* two classes ON PURPOSE: a composed rail (e.g. side-rail) may carry its own `position:
148
+ relative` (the icon gutter), and the CSS bundle sorts side-rail AFTER app-shell — at equal
149
+ specificity the drawer's `fixed` silently lost and the rail fell back into the grid flow.
150
+ The extra ancestor class keeps the drawer winning regardless of bundle order. */
151
+ .app-shell .app-shell__rail {
152
+ position: fixed; inset: 0 auto 0 0; z-index: 40;
153
+ width: min(78vw, 18rem);
154
+ transform: translateX(-100%); transition: transform 0.3s ease;
155
+ border-right: 1px solid var(--color-line); background: var(--color-surface);
156
+ }
157
+ .app-shell[data-rail-open="true"] .app-shell__rail { transform: none; }
158
+ .app-shell__scrim {
159
+ display: block; position: fixed; inset: 0; z-index: 39;
160
+ background: color-mix(in srgb, var(--ink) 32%, transparent);
161
+ opacity: 0; pointer-events: none; transition: opacity 0.3s ease;
162
+ }
163
+ .app-shell[data-rail-open="true"] .app-shell__scrim { opacity: 1; pointer-events: auto; }
164
+ }
165
+
166
+ @media (prefers-reduced-motion: reduce) {
167
+ .app-shell__rail, .app-shell__scrim { transition: none; }
168
+ }
169
+
170
+ /* ---- viewport preview (shell.js: data-shell="viewport-toggle") — clamps `<body>`, the SAME
171
+ element the @container queries above read (`shell-frame`), not `.app-shell`. That's what makes
172
+ this a real (if imperfect) breakpoint drive now instead of a cosmetic frame: shrinking body's
173
+ inline-size shrinks the container, so the toggle fires the identical mobile/tablet layout a real
174
+ narrow window does — the rail becomes a drawer, the aside hides, etc. Still not a full device
175
+ emulator (no simulated touch/DPR, and app-window.css's OWN backdrop/title-bar collapse — a
176
+ separate `@media` — can't follow suit: that rule restyles `body.app-window-backdrop` itself,
177
+ and a container may never query its own condition, only a descendant's; see that file). The
178
+ shell's framed border stays keyed off `.app-shell` (a descendant of body, so this is legal) so
179
+ the visual frame still hugs the shell's own edge, not body's padding box. */
180
+ body[data-viewport] { max-width: var(--shell-viewport-w, 100%); margin-inline: auto; }
181
+ body[data-viewport] .app-shell { border-inline: 1px solid var(--color-line); }
182
+ body[data-viewport="tablet"] { --shell-viewport-w: 48rem; }
183
+ body[data-viewport="mobile"] { --shell-viewport-w: 24.4rem; }
184
+
185
+ /* ---- single-page feel: the shell chrome PERSISTS across cross-document navigations (each name is
186
+ present once per page, so it morphs in place); only <main> is in the root snapshot and cross-fades.
187
+ Reduced-motion disables view transitions globally (grain/styles/global.css). ---- */
188
+ .app-shell__rail { view-transition-name: shell-rail; }
189
+ .app-shell__topbar { view-transition-name: shell-topbar; }
190
+ .app-shell__aside { view-transition-name: shell-aside; }
191
+ .app-shell__console { view-transition-name: shell-console; }
192
+ .app-shell__window { view-transition-name: shell-window; }
193
+ .app-shell__status { view-transition-name: shell-status; }
@@ -0,0 +1,58 @@
1
+ # App shell
2
+
3
+ The **workspace** layout — the "work-y" archetype that coexists with the single-column
4
+ editorial `.container`. A full-viewport CSS grid of five regions: a left **rail**, a top
5
+ **bar**, the **main** pane, a right **aside** (the assistant), and a bottom **console**.
6
+
7
+ It hosts arbitrary content, so it's a layout you apply with region classes (not a
8
+ data-bound tag): put `class="app-shell"` on the frame and drop content into
9
+ `app-shell__rail` / `__topbar` / `__main` / `__aside` / `__console`. `data-rail-collapsed`
10
+ narrows the rail to icons; on mobile the rail becomes a drawer (`data-rail-open`) over a
11
+ `app-shell__scrim`. See the live composition on any page of the reference app (it's the EDITOR
12
+ chrome — `tjakoen.github.io`'s `portfolio-frame`).
13
+
14
+ **Parent context (implicit, self-installing).** `.app-shell` must be a direct-or-nested child of
15
+ `<body>` — every real composition already is. `app-shell.css` sets `container-type: inline-size`
16
+ on `body:has(.app-shell)` (named `shell-frame`) because the shell's own mobile/tablet layout
17
+ breakpoints restyle `.app-shell`'s OWN grid properties, and an element can never `@container`-query
18
+ a condition on itself — only a descendant can query an ancestor container. Using `body` (rather
19
+ than a purpose-built wrapper) means the real narrow-viewport case works with zero JS; the
20
+ viewport-toggle (`data-shell="viewport-toggle"`) clamps `body[data-viewport]`'s max-width so its
21
+ preview shrinks the same container a real narrow window does. `sidebar-panel` and `status-bar`
22
+ share this container for their own mobile rules. One documented gap: `app-window`'s backdrop
23
+ padding lives on `body` itself (`.app-window-backdrop`), so it can't follow suit — it stays a real
24
+ `@media` and only responds to a genuinely narrow window, not the toggle preview.
25
+
26
+ Two **optional full-width rows** bracket the workspace: `__window` (top — the `app-window`
27
+ title bar) and `__status` (bottom — the `status-bar`). They're auto rows, so a shell that
28
+ places nothing in them renders exactly as before; fill them to dress the shell as an editor
29
+ window (see `app-window` + `status-bar`).
30
+
31
+ **Activity bar (opt-in).** Put an `activity-bar` (the VS Code icon column) as the FIRST child of
32
+ `__rail` (or of `.rail-body`, see below), with a nested `.side-rail` beside it: the container
33
+ becomes a flex row (rule lives in this sheet, alongside the mobile-drawer rules, so bundle order
34
+ can't break the drawer). A rail without one is untouched. Collapsing the rail then leaves the icon
35
+ strip only. See `activity-bar.md`.
36
+
37
+ **Rail head (opt-in).** Put a full-width `.rail-head` (a brand/title row) as the FIRST child of
38
+ `__rail`, followed by a `.rail-body` wrapping everything else (the activity-bar + side-rail row,
39
+ or a bare side-rail): the rail stacks vertically, the head sitting flush with the topbar row beside
40
+ it, everything else starting on its own line underneath. Skip both and the rail is untouched.
41
+
42
+ ## Structure (capped height for the catalog; real one is `100dvh`)
43
+
44
+ ```html
45
+ <div class="app-shell" data-rail-collapsed="false" style="height:280px">
46
+ <aside class="app-shell__rail side-rail">
47
+ <div class="side-rail__brand"><b-icon sym="/assets/sprite.svg#spark"></b-icon><span>Grain</span></div>
48
+ <a class="nav-item" aria-current="page"><b-icon sym="/assets/sprite.svg#loop"></b-icon><span class="nav-item__label">Overview</span></a>
49
+ <a class="nav-item"><b-icon sym="/assets/sprite.svg#tasks"></b-icon><span class="nav-item__label">Tasks</span></a>
50
+ </aside>
51
+ <div class="app-shell__topbar">
52
+ <nav class="tab-bar"><a class="tab" aria-current="page">Overview</a><a class="tab">Tasks</a></nav>
53
+ </div>
54
+ <main class="app-shell__main" style="padding:1rem">Main content.</main>
55
+ <aside class="app-shell__aside" style="padding:1rem">Assistant.</aside>
56
+ <section class="app-shell__console" style="padding:.5rem 1rem">✶ the AI — idle</section>
57
+ </div>
58
+ ```
@@ -0,0 +1,74 @@
1
+ // grain/components/organisms/app-shell/app-shell.test.ts — DRIFT GUARD for the 2026-07-14
2
+ // responsive-polish fix. `.app-shell` can never legally `@container`-query a condition on itself
3
+ // (CSS containment spec: a container never matches its own query, only a descendant's), so its two
4
+ // real layout breakpoints (and the sibling shell files that share the same mobile boundary:
5
+ // sidebar-panel's bottom sheet, status-bar's narrow trim) moved from `@media (max-width: …)` — which
6
+ // only ever reads the real browser viewport, so the shell's own viewport-toggle clamp never
7
+ // triggered them (grain lesson: a documented behavior the mechanism can't render is worse than none)
8
+ // — to `@container shell-frame (max-width: …)`, a named container established on `<body>`. This test
9
+ // is the grep-style guard (lesson 5): it fails the build the moment any of these files regress back
10
+ // to a self-defeating `@media` layout breakpoint, rather than relying on a human to notice the shell
11
+ // silently stopped responding to its own preview toggle again.
12
+ import { test, expect } from "bun:test";
13
+ import { readFileSync } from "node:fs";
14
+ import { join } from "node:path";
15
+
16
+ const root = join(import.meta.dir, "..", "..", "..");
17
+ const read = (rel: string) => readFileSync(join(root, rel), "utf8");
18
+
19
+ const appShellCss = read("components/organisms/app-shell/app-shell.css");
20
+ const appWindowCss = read("components/organisms/app-window/app-window.css");
21
+ const sidebarPanelCss = read("components/organisms/sidebar-panel/sidebar-panel.css");
22
+ const statusBarCss = read("components/organisms/status-bar/status-bar.css");
23
+ const shellJs = read("scripts/shell.js");
24
+
25
+ // a max-width/min-width @media that ISN'T prefers-reduced-motion — i.e. a real layout breakpoint.
26
+ const MEDIA_LAYOUT_BP = /@media\s*\([^)]*(?:max|min)-width[^)]*\)/g;
27
+
28
+ test("app-shell.css establishes the shell-frame container on <body>, not on .app-shell itself", () => {
29
+ // scoped with :has() so pages without a shell are untouched; named so descendants (app-shell +
30
+ // sidebar-panel + status-bar) all resolve against the SAME container regardless of future nesting.
31
+ expect(appShellCss).toMatch(/body:has\(\.app-shell\)\s*\{[^}]*container-type:\s*inline-size/);
32
+ expect(appShellCss).toMatch(/body:has\(\.app-shell\)\s*\{[^}]*container-name:\s*shell-frame/);
33
+ });
34
+
35
+ test("app-shell.css's own layout breakpoints are @container, not @media (the self-query trap)", () => {
36
+ expect(appShellCss).not.toMatch(MEDIA_LAYOUT_BP);
37
+ expect(appShellCss).toMatch(/@container shell-frame \(max-width: 1100px\)/);
38
+ expect(appShellCss).toMatch(/@container shell-frame \(max-width: 768px\)/);
39
+ });
40
+
41
+ test("sidebar-panel + status-bar mobile rules follow the shell's container, not a stale @media", () => {
42
+ for (const [name, css] of [["sidebar-panel.css", sidebarPanelCss], ["status-bar.css", statusBarCss]] as const) {
43
+ expect(css, `${name} still has a real-viewport-only layout @media`).not.toMatch(MEDIA_LAYOUT_BP);
44
+ expect(css, `${name} lost its @container shell-frame mobile rule`).toMatch(/@container shell-frame \(max-width: 768px\)/);
45
+ }
46
+ });
47
+
48
+ // app-window.css is the ONE documented exception: `.app-window-backdrop` IS <body> itself (the
49
+ // class lives on <body> in every real composition), and an element can never legally
50
+ // @container-query its own condition — only `.app-window-backdrop { padding: 0 }` may stay a real
51
+ // @media. Guard BOTH halves: the exception doesn't silently grow, and the descendant rules
52
+ // (`.app-shell.app-window`, `.window-bar`) don't regress back to @media now that they don't have to.
53
+ test("app-window.css keeps exactly the documented self-query exception, converts the rest", () => {
54
+ const mediaBlocks = [...appWindowCss.matchAll(MEDIA_LAYOUT_BP)];
55
+ expect(mediaBlocks.length).toBe(1);
56
+ // the surviving @media must be the narrow one that touches only the backdrop padding.
57
+ const afterMedia = appWindowCss.slice(mediaBlocks[0].index);
58
+ const mediaBody = afterMedia.slice(0, afterMedia.indexOf("}") + 1);
59
+ expect(mediaBody).toMatch(/\.app-window-backdrop\s*\{\s*padding:\s*0/);
60
+ expect(mediaBody).not.toMatch(/\.app-shell\.app-window|\.window-bar/);
61
+ expect(appWindowCss).toMatch(/@container shell-frame \(max-width: 768px\)\s*\{[^}]*\.app-shell\.app-window/);
62
+ expect(appWindowCss).toMatch(/\.window-bar\s*\{\s*display:\s*none/);
63
+ });
64
+
65
+ test("the viewport-toggle clamps body[data-viewport], not .app-shell[data-viewport] — that's what makes it a real container shrink", () => {
66
+ expect(appShellCss).toMatch(/body\[data-viewport\]\s*\{[^}]*max-width:\s*var\(--shell-viewport-w/);
67
+ expect(appShellCss).not.toMatch(/\.app-shell\[data-viewport\]\s*\{[^}]*max-width/);
68
+ expect(shellJs).toMatch(/document\.body\.setAttribute\("data-viewport"/);
69
+ expect(shellJs).toMatch(/document\.body\.getAttribute\("data-viewport"\)/);
70
+ });
71
+
72
+ test("reduced-motion queries stay real @media (they read a user preference, not a size)", () => {
73
+ expect(appShellCss).toMatch(/@media \(prefers-reduced-motion: reduce\)/);
74
+ });
@@ -0,0 +1,111 @@
1
+ /* organisms/app-window — the EDITOR-WINDOW frame: the whole app boxed in a bordered,
2
+ radiused window sitting on a darker backdrop, with a title bar up top. CSS-only pattern
3
+ (no .html — it dresses the app-shell; see app-window.md for the parent contract):
4
+
5
+ <body class="app-window-backdrop">
6
+ <div class="app-shell app-window">
7
+ <header class="app-shell__window window-bar">…</header> ← the title bar row
8
+ … the shell's regions …
9
+ <footer class="app-shell__status status-bar">…</footer> ← see status-bar
10
+ </div>
11
+ </body>
12
+
13
+ The app-shell grid owns the ROWS (app-shell.css: "window" / "status"); this file owns the
14
+ LOOK: hairline frame, print-style solid offset shadow (no blur). The title bar hosts, left
15
+ to right: the WINDOW NAV (functional icon buttons: back / refresh / forward — glyphs always
16
+ visible, hover goes to our fg color, never OS traffic-lights), an optional control cluster
17
+ (`__ctl`), a centered title OR search field (`__title` / `__search`), and a symmetry spacer
18
+ (`__end`). Tokens only; re-themes for free. */
19
+
20
+ /* the backdrop: the page behind the window, a shade darker than the paper */
21
+ .app-window-backdrop {
22
+ background: color-mix(in srgb, var(--ink) 12%, var(--paper));
23
+ padding: clamp(0.5rem, 2vh, 1.5rem);
24
+ height: 100dvh;
25
+ box-sizing: border-box;
26
+ }
27
+
28
+ /* the frame: pairs with .app-shell (which sets height: 100dvh — inside the padded
29
+ backdrop the window fills what's left, hence the higher-specificity override) */
30
+ .app-shell.app-window { height: 100%; }
31
+ .app-window {
32
+ border: 1px solid var(--ink);
33
+ border-radius: var(--radius-md);
34
+ overflow: hidden;
35
+ box-shadow: 4px 4px 0 color-mix(in srgb, var(--ink) 30%, transparent); /* print-style, zero blur */
36
+ }
37
+
38
+ /* ---- the title bar ---- */
39
+ .window-bar {
40
+ display: flex; align-items: center; gap: var(--space-4);
41
+ padding: 0.4rem 0.9rem;
42
+ background: var(--color-surface);
43
+ border-bottom: 1px solid var(--color-line);
44
+ font-family: var(--font-mono);
45
+ font-size: var(--text-xs);
46
+ color: var(--color-muted);
47
+ }
48
+
49
+ /* the window nav — OS-window CIRCLES, but carrying functional icons (back / refresh / forward):
50
+ round hairline buttons with the glyph ALWAYS visible (quiet muted ink at rest); hover/focus
51
+ goes to our fg + accent tint — no OS traffic-light colors. */
52
+ .window-bar__nav { display: flex; align-items: center; gap: 0.4rem; }
53
+ .window-bar__nav button {
54
+ all: unset; box-sizing: border-box; cursor: pointer;
55
+ display: inline-flex; align-items: center; justify-content: center;
56
+ width: 1.15rem; height: 1.15rem; border-radius: 50%;
57
+ border: 1px solid var(--color-muted);
58
+ color: var(--color-muted); line-height: 1;
59
+ }
60
+ .window-bar__nav button:hover {
61
+ color: var(--color-fg); border-color: var(--color-fg);
62
+ background: color-mix(in srgb, var(--color-accent) 14%, transparent);
63
+ }
64
+ .window-bar__nav button:focus-visible { outline: 1px solid var(--color-accent); outline-offset: 2px; }
65
+ .window-bar__nav .icon { width: 0.72rem; height: 0.72rem; }
66
+
67
+ /* the control cluster — theme/scheme/view toggles. Sits on the RIGHT (the left is only the OS
68
+ circle buttons); the flex:1 search between them keeps it pinned to the trailing edge. */
69
+ .window-bar__ctl { display: flex; align-items: center; gap: var(--space-3); flex: none; }
70
+ .window-bar__ctl button { all: unset; cursor: pointer; font: inherit; color: inherit; }
71
+ .window-bar__ctl button:hover { color: var(--color-fg); }
72
+ .window-bar__ctl button:focus-visible { outline: 1px solid var(--color-accent); outline-offset: 2px; }
73
+
74
+ /* centered title (plain text form) */
75
+ .window-bar__title { flex: 1; text-align: center; letter-spacing: 0.06em;
76
+ white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
77
+
78
+ /* centered SEARCH form: a button drawn as an input (it opens the ⌘K palette) — the editor's
79
+ center search field. The placeholder text is the consumer's (e.g. the page's breadcrumb). */
80
+ .window-bar__search {
81
+ all: unset; box-sizing: border-box; cursor: pointer;
82
+ flex: 1; max-width: 34rem; margin-inline: auto;
83
+ display: flex; align-items: center; gap: var(--space-2); justify-content: center;
84
+ padding: 0.15rem 0.7rem;
85
+ border: 1px solid var(--color-line); border-radius: var(--radius-sm);
86
+ background: var(--color-bg);
87
+ font: inherit; color: var(--color-muted);
88
+ white-space: nowrap; overflow: hidden;
89
+ }
90
+ .window-bar__search:hover { border-color: var(--color-muted); }
91
+ .window-bar__search:focus-visible { outline: 1px solid var(--color-accent); outline-offset: 2px; }
92
+
93
+ /* ---- mobile: the window collapses — no backdrop padding, no frame, no title bar
94
+ (the shell's drawer chrome carries the brand there); the status bar stays.
95
+
96
+ SPLIT ON PURPOSE (2026-07-14): app-shell.css turns its own layout breakpoints into
97
+ `@container shell-frame`, keyed to `<body>` — but `.app-window-backdrop` IS `<body>` itself
98
+ (see the class on `<body>` in the comment up top), and a container can never legally query its
99
+ own condition, only a descendant's (CSS containment spec). So the backdrop padding stays a real
100
+ `@media`: it tracks a real narrow WINDOW correctly, but the shell's viewport-toggle preview
101
+ (which clamps body's width, not the real viewport) can't collapse it — a known, harmless gap in
102
+ a demo-only feature. `.app-shell.app-window` and `.window-bar`, though, are DESCENDANTS of body,
103
+ not body itself, so they're free to follow the container — converted, so the toggle's preview at
104
+ least drops the frame border/shadow/title-bar even though the backdrop margin lingers. ---- */
105
+ @media (max-width: 768px) {
106
+ .app-window-backdrop { padding: 0; }
107
+ }
108
+ @container shell-frame (max-width: 768px) {
109
+ .app-shell.app-window { border: 0; border-radius: 0; box-shadow: none; }
110
+ .window-bar { display: none; }
111
+ }
@@ -0,0 +1,53 @@
1
+ # app-window
2
+
3
+ The **editor-window frame**: boxes the whole app in a bordered, radiused window on a darker
4
+ backdrop, with a title bar up top. Pairs with `status-bar` for the bottom row. CSS-only (no
5
+ `.html`): it *dresses* an `app-shell`, it doesn't render content.
6
+
7
+ **Parent contract (required):** apply `.app-window` **on the `.app-shell` element itself** and
8
+ `.app-window-backdrop` on `<body>`; the title bar is a `.window-bar` placed in the shell's
9
+ `.app-shell__window` grid row (app-shell.css owns the rows). Without an `app-shell` grid around
10
+ it, `.window-bar` is just a flex strip — the frame and rows come from the shell.
11
+
12
+ The title bar hosts, left to right:
13
+
14
+ - **`__dots`** — the window dots. Plain `<i><i><i>` for a decorative cluster (one filled, two
15
+ hollow ink circles), or functional `<button>`s marked `data-window-close` / `data-window-clear`
16
+ / `data-window-back`. At rest every dot reads as quiet ink; hovering the cluster reveals each
17
+ dot's muted accent + glyph (`--color-dot-*` tokens — the one sanctioned traffic-light exception
18
+ to the closed palette). The *behavior* is the consumer's (wire the clicks in your app script);
19
+ give each a `title` tooltip.
20
+ - **`__ctl`** *(optional)* — a small control cluster (theme cycle, scheme toggle, pane toggles):
21
+ unstyled text buttons, status-weight.
22
+ - **`__title`** *or* **`__search`** — the centered element. `__title` is plain mono text;
23
+ `__search` is a *button drawn as an input* that opens the app's command palette (⌘K) — its text
24
+ is the consumer's placeholder (e.g. the current page's breadcrumb).
25
+ - **`__end`** — a symmetry spacer; give it a width matching the leading cluster so the center
26
+ stays centered.
27
+
28
+ ```html
29
+ <body class="app-window-backdrop">
30
+ <div class="app-shell app-window" data-surface="screen">
31
+ <header class="app-shell__window window-bar">
32
+ <span class="window-bar__dots">
33
+ <button type="button" data-window-close title="Close">×</button>
34
+ <button type="button" data-window-clear title="Clear cached data">⌫</button>
35
+ <button type="button" data-window-back title="Back">‹</button>
36
+ </span>
37
+ <span class="window-bar__ctl">
38
+ <button type="button" data-cycle-theme title="Cycle theme">◆</button>
39
+ <button type="button" data-toggle-scheme title="Light / dark">◐</button>
40
+ </span>
41
+ <button class="window-bar__search" type="button"><b-kbd keys="⌘K"></b-kbd> my-app › page</button>
42
+ <span class="window-bar__end" style="width: 7rem"></span>
43
+ </header>
44
+ <!-- rail / topbar / main / aside / console … -->
45
+ <footer class="app-shell__status status-bar">…</footer>
46
+ </div>
47
+ </body>
48
+ ```
49
+
50
+ - On mobile the window collapses: no backdrop padding, no frame, the title bar hides (the
51
+ shell's drawer chrome carries the brand); the `status-bar` row stays.
52
+ - Tokens only — the frame re-themes with every flavor; the shadow is print-style solid offset,
53
+ zero blur (DESIGN-SYSTEM §6).
@@ -0,0 +1,5 @@
1
+ /* organisms/chat-log — a vertical thread of chat-message molecules. chat-message positions itself
2
+ with align-self (you → right, the AI → left), which ONLY works inside a flex COLUMN — so the log
3
+ is required, not optional. Composing messages in a chat-log makes correct alignment structural
4
+ (correct-by-construction) instead of a silent trap. */
5
+ .chat-log { display: flex; flex-direction: column; gap: var(--space-2); }
@@ -0,0 +1,14 @@
1
+ # Chat log
2
+
3
+ A vertical thread that lays out `chat-message`s. Each `chat-message` positions itself — **you** to the
4
+ right, **the AI** to the left — via `align-self`, which only works inside a flex column. The chat-log
5
+ provides that column, so messages **can't silently misalign**: compose them here, not in a bare `div`.
6
+
7
+ ## Thread
8
+
9
+ ```html
10
+ <div class="chat-log">
11
+ <div class="chat-message" data-role="you"><span class="chat-message__who">You</span><span class="chat-message__body">Plan my Thursday.</span></div>
12
+ <div class="chat-message" data-role="ai" data-grade="grain"><span class="chat-message__who">GRAIN</span><span class="chat-message__body">On it — three deep-work blocks, review at 2.</span></div>
13
+ </div>
14
+ ```
@@ -0,0 +1,31 @@
1
+ # Code editor
2
+
3
+ When the AI is writing into the editor, the whole panel wears the **non-text grain**: a dashed
4
+ "terminal" edge (the same signal code-block uses when the AI authors a block). It settles back to
5
+ a solid frame on commit — the moment the human owns the buffer again. Inherited grade works too:
6
+ any `[data-grade="grain"]` ancestor puts the panel in-transit without touching the root.
7
+
8
+ ## In-transit
9
+
10
+ ### AI writing a spec
11
+ ```html
12
+ <div class="code-editor" data-commit="pending" style="height:12rem">
13
+ <div class="code-editor__bar">
14
+ <span class="code-editor__title">tests/checkout.spec.ts</span>
15
+ <span class="code-editor__dirty">• writing…</span>
16
+ </div>
17
+ <div class="code-editor__mount"><pre class="code-block"><code>await page.goto('/checkout');</code></pre></div>
18
+ <div class="code-editor__status">Drafting…</div>
19
+ </div>
20
+ ```
21
+
22
+ ### Inherited grade
23
+ ```html
24
+ <div data-grade="grain">
25
+ <div class="code-editor" style="height:8rem">
26
+ <div class="code-editor__bar"><span class="code-editor__title">spec.ts</span></div>
27
+ <div class="code-editor__mount"></div>
28
+ <div class="code-editor__status">Ready</div>
29
+ </div>
30
+ </div>
31
+ ```