@poveste/app 0.15.0 → 0.16.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/app",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Pre-bundled UI for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -31,39 +31,43 @@
     "src"
   ],
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": ">=22.22.2"
   },
   "dependencies": {
-    "@poveste/controls": "^0.15.0",
-    "@poveste/shared": "^0.15.0",
-    "@poveste/vendors": "^0.15.0",
+    "@poveste/controls": "^0.16.1",
+    "@poveste/shared": "^0.16.1",
+    "@poveste/vendors": "^0.16.1",
     "fuse.js": "^7.0.0",
     "shiki": "^4.4.3"
   },
   "devDependencies": {
     "@fontsource/noto-sans-display": "^5.3.0",
-    "@iconify-json/carbon": "^1.2.25",
-    "@iconify-json/fluent": "1.2.56",
+    "@iconify-json/carbon": "^1.2.27",
+    "@iconify-json/fluent": "1.2.58",
     "@iconify-json/mdi": "^1.2.3",
     "@iconify-json/ri": "^1.2.10",
-    "@iconify/utils": "^3.1.4",
+    "@iconify/utils": "^3.1.7",
+    "@iconify/vue": "^5.0.3",
     "@tailwindcss/postcss": "^4.3.3",
-    "@tailwindcss/typography": "^0.5.15",
+    "@tailwindcss/typography": "^0.5.20",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^22.10.1",
-    "@vitejs/plugin-vue": "^6.0.0",
+    "@types/node": "^26.6.3",
+    "@vitejs/plugin-vue": "^6.0.9",
+    "@vueuse/core": "^15.0.0",
     "chokidar": "^5.0.0",
     "concurrently": "^10.0.5",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.4.1",
     "globby": "^16.2.4",
     "pathe": "^2.0.3",
+    "pinia": "^4.0.3",
     "postcss": "^8.5.23",
     "postcss-cli": "^12.0.0",
     "tailwindcss": "^4.3.3",
     "typescript": "6.0.3",
-    "vite": "^8.2.0",
-    "vitest": "^5.0.0",
-    "vue": "^3.5.26",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1",
     "vue-tsc": "^3.3.11"
   },
   "scripts": {

package/src/__tests__/base-select.spec.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/*
+ * The same defect as `@poveste/controls`' own select, in the chrome's copy: the
+ * options are portalled to `body`, which carries no colour, so a background
+ * without a text colour left them at the UA default — black on the dark panel.
+ *
+ * `__dirname` rather than `import.meta.url`, which vitest's transform does not
+ * leave intact here — the trap `icons.spec.ts` records.
+ */
+const source = readFileSync(resolve(__dirname, '../app/components/base/BaseSelect.vue'), 'utf8')
+
+describe('the chrome select options', () => {
+  const classes = /class="poveste-base-select-options([^"]*)"/.exec(source)?.[1] ?? ''
+
+  it('carries a text colour, not only a background', () => {
+    expect(classes).toMatch(/\btext-gray-\d+\b/)
+  })
+
+  it('carries one for dark as well', () => {
+    expect(classes).toMatch(/\bdark:text-gray-\d+\b/)
+  })
+})

package/src/__tests__/reset.spec.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/*
+ * Preflight is deliberately off and `main.pcss` replaces it by hand, so anything
+ * the replacement leaves out is a UA default the chrome then renders. The one
+ * that shipped was the button background: `ButtonFace` reads as a light grey
+ * panel, close enough to the light chrome to pass review and a white hole in dark.
+ *
+ * Asserted against the source rather than the built sheet because the build is
+ * postcss over this file, and a reader looking for the reset looks here.
+ */
+// `__dirname` rather than `import.meta.url`, which vitest's transform does not
+// leave intact here — the same trap `icons.spec.ts` records.
+//
+// Line endings normalised, and the anchor below is a single line: matching a
+// selector list *across* its own line break reads the file as the checkout wrote
+// it, which on Windows is CRLF. This found nothing there and passed everywhere
+// else, which is the worst way for a check to be wrong.
+const source = readFileSync(resolve(__dirname, '../app/style/main.pcss'), 'utf8').replace(/\r\n/g, '\n')
+
+/** The declarations of the first rule whose selector list contains `anchor`. */
+function rule(anchor: string) {
+  const start = source.indexOf(anchor)
+  if (start === -1) {
+    return null
+  }
+  const open = source.indexOf('{', start)
+  return source.slice(open + 1, source.indexOf('}', open))
+}
+
+/** The last line of the button reset's selector list. */
+const BUTTON_RESET = '[type=\'submit\']'
+
+describe('the manual Preflight replacement', () => {
+  it('clears the UA background off a button', () => {
+    expect(rule(BUTTON_RESET)).toContain('background-color: transparent')
+  })
+
+  it('clears the UA background image too', () => {
+    // Preflight resets both; a gradient theme would otherwise come back.
+    expect(rule(BUTTON_RESET)).toContain('background-image: none')
+  })
+
+  it('stays inside `@layer base`, where a utility can still win', () => {
+    // An unlayered rule beats every layered one, so `bg-*` on a button would stop
+    // working — the trap the file's own comment records.
+    const layers = [...source.matchAll(/@layer base \{/g)].map(match => match.index)
+    const button = source.indexOf('background-color: transparent')
+    expect(layers.some(start => start < button)).toBe(true)
+  })
+})

package/src/__tests__/state-clone.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
-import { toPresetState } from '../app/util/state'
+import { markRaw, ref } from 'vue'
+import { toPresetState, toRawDeep } from '../app/util/state'
 
 /**
  * What the state-presets panel does to a variant's state before storing it.
@@ -64,3 +65,56 @@ describe('a variant\'s state as a preset', () => {
     expect(preset.recursiveParameter.name).toBe('hello')
   })
 })
+
+describe('a binding Vue has marked raw', () => {
+  it('is dropped from what leaves the realm, rather than passed through', () => {
+    const graph = markRaw({ nodes: { deep: { deeper: 1 } } })
+
+    // `clean` means this copy is posted or persisted. `__v_skip` is
+    // non-enumerable and does not survive `structuredClone`, so passing the
+    // value would hand the far side an unmarked graph to deep-watch — which is
+    // the hanging story #957 describes. The key does not go.
+    expect(toRawDeep({ text: 'a', graph }, true)).toEqual({ text: 'a' })
+  })
+
+  it('is carried by reference when the copy stays in this realm', () => {
+    const graph = markRaw({ nodes: { deep: 1 } })
+    const copied = toRawDeep({ text: 'a', graph })
+
+    // Same identity, not a rebuilt one: that is what lets the compare settle it
+    // by `Object.is` instead of walking whatever is behind it.
+    expect(copied.graph).toBe(graph)
+    expect(copied.text).toBe('a')
+  })
+
+  it('is unwrapped from a ref first, which is the shape a template ref has', () => {
+    const graph = ref(markRaw({ nodes: { deep: 1 } }))
+
+    expect(toRawDeep({ graph }, true)).toEqual({})
+    expect(toRawDeep({ graph }).graph).toBe(graph.value)
+  })
+
+  it('leaves an array the way a function does', () => {
+    // Filtered, indices and all. Stated because it is a real consequence and
+    // not an obviously right one — it is the rule functions already follow.
+    expect(toRawDeep({ list: [1, markRaw({ a: 1 }), 2] }, true)).toEqual({ list: [1, 2] })
+  })
+
+  it('does not take the whole state with it when the state itself is marked', () => {
+    expect(toRawDeep(markRaw({ text: 'a' }), true)).toEqual({})
+  })
+
+  it('takes only itself when it sits inside an ordinary object', () => {
+    const state = { config: { zoom: 3, map: markRaw({ tiles: { deep: 1 } }) } }
+
+    // The far side keeps whatever it had under `config.map`, because a key that
+    // is not sent is a key `applyState` cannot overwrite — it merges one level.
+    expect(toRawDeep(state, true)).toEqual({ config: { zoom: 3 } })
+  })
+
+  it('never reaches a preset', () => {
+    const graph = markRaw({ nodes: { deep: 1 } })
+
+    expect(toPresetState({ count: 1, graph })).toEqual({ count: 1 })
+  })
+})

package/src/__tests__/state-types.spec.ts

@@ -0,0 +1,175 @@
+import { isEquivalent } from '@poveste/shared'
+import { describe, expect, it } from 'vitest'
+import { markRaw, reactive } from 'vue'
+import { toRawDeep } from '../app/util/state'
+
+/**
+ * What the walker does to a value that is not a plain object.
+ *
+ * `postMessage` is structured clone, so structured clone is the boundary that
+ * actually exists — and it carries `Date`, `Map`, `Set`, `RegExp`, `Error`,
+ * typed arrays and `BigInt` intact. The walker flattened all of them to `{}`
+ * before the transport was ever reached, so the question is not which types to
+ * support but which ones we were destroying on the way (#977).
+ */
+class Point {
+  constructor(public x: number, public y: number) {}
+  get len() { return Math.hypot(this.x, this.y) }
+}
+
+describe('a value the transport can carry', () => {
+  it('keeps a Date, rather than emptying it', () => {
+    const out = toRawDeep({ at: new Date(1790071200000) }, true)
+
+    expect(out.at).toBeInstanceOf(Date)
+    expect(out.at.getTime()).toBe(1790071200000)
+  })
+
+  it('keeps a Map and a Set with their contents', () => {
+    const out = toRawDeep({ m: new Map([['a', 1]]), s: new Set([1, 2, 3]) }, true)
+
+    expect(out.m).toBeInstanceOf(Map)
+    expect(out.m.get('a')).toBe(1)
+    expect(out.s).toBeInstanceOf(Set)
+    expect(out.s.size).toBe(3)
+  })
+
+  it('keeps a RegExp and an Error', () => {
+    const out = toRawDeep({ re: /ab+c/gi, err: new Error('boom') }, true)
+
+    expect(out.re).toBeInstanceOf(RegExp)
+    expect(out.re.source).toBe('ab+c')
+    expect(out.err).toBeInstanceOf(Error)
+    expect(out.err.message).toBe('boom')
+  })
+
+  it('keeps a typed array as one, rather than as an index map', () => {
+    const out = toRawDeep({ bytes: new Uint8Array([1, 2, 3]) }, true)
+
+    expect(out.bytes).toBeInstanceOf(Uint8Array)
+    expect([...out.bytes]).toEqual([1, 2, 3])
+  })
+
+  it('detaches it, so a later mutation does not reach the copy', () => {
+    const at = new Date(1790071200000)
+    const out = toRawDeep({ at }, true)
+
+    at.setTime(0)
+
+    expect(out.at.getTime()).toBe(1790071200000)
+  })
+})
+
+describe('a value the transport refuses', () => {
+  it('drops a URL rather than flattening it, the way a function is dropped', () => {
+    // Structured clone throws `DataCloneError` on a `URL`. Passing it through
+    // would turn a silent flattening into a thrown exception mid-sync, which is
+    // worse than what it replaces.
+    const out = toRawDeep({ href: new URL('https://poveste.dev/a'), kept: 1 }, true)
+
+    expect(Object.hasOwn(out, 'href')).toBe(false)
+    expect(out.kept).toBe(1)
+  })
+
+  it('leaves what it did send intact', () => {
+    const out = toRawDeep({ before: 1, href: new URL('https://poveste.dev/a'), after: 2 }, true)
+
+    expect(out).toEqual({ before: 1, after: 2 })
+  })
+})
+
+describe('a class instance', () => {
+  // Structured clone carries own fields and drops the prototype, so "faithful"
+  // has no meaning here. Plain is the answer, and it is now a stated one.
+  it('arrives as plain data, with its fields but not its accessors', () => {
+    const out = toRawDeep({ p: new Point(3, 4) }, true)
+
+    expect(out.p).toEqual({ x: 3, y: 4 })
+    expect(out.p.len).toBeUndefined()
+  })
+})
+
+describe('the two halves of the sync agree', () => {
+  // `isEquivalent` refuses to compare anything that is not a plain object,
+  // because "two distinct `Date`s would otherwise compare equal on an empty key
+  // list". That defence could not fire: it is handed the walker's output, and
+  // by then the `Date` was already `{}` (#977).
+  it('so two different dates are not equivalent after the walk', () => {
+    const a = toRawDeep({ at: new Date(1790071200000) }, true)
+    const b = toRawDeep({ at: new Date(0) }, true)
+
+    expect(isEquivalent(a, b)).toBe(false)
+  })
+
+  it('and the in-realm walk carries one by reference, which `Object.is` settles', () => {
+    const at = new Date(1790071200000)
+
+    expect(toRawDeep({ at }, false).at).toBe(at)
+  })
+})
+
+describe('a value that is reactive, which state always is', () => {
+  // The one that would have shipped a second silent failure. Vue proxies `Map`
+  // and `Set` but not `Date`, `RegExp`, `Error` or typed arrays, and
+  // `structuredClone` throws `DataCloneError` on the proxy while the raw
+  // object clones fine. Without `toRaw` a `Map` in reactive state is refused
+  // here and dropped — a different silence, not a fix for the first.
+  it('clones a reactive Map rather than refusing it', () => {
+    const state = reactive({ m: new Map([['a', 1]]) })
+
+    const out = toRawDeep(state, true)
+
+    expect(out.m).toBeInstanceOf(Map)
+    expect(out.m.get('a')).toBe(1)
+  })
+
+  it('clones a reactive Set the same way', () => {
+    const out = toRawDeep(reactive({ s: new Set([1, 2]) }), true)
+
+    expect(out.s).toBeInstanceOf(Set)
+    expect(out.s.size).toBe(2)
+  })
+
+  it('and a reactive Date, which Vue does not proxy', () => {
+    const out = toRawDeep(reactive({ at: new Date(1790071200000) }), true)
+
+    expect(out.at.getTime()).toBe(1790071200000)
+  })
+})
+
+describe('this walk\'s own rules reach inside a Map and a Set', () => {
+  // An array already comes out shorter for a function or a marked value. A
+  // container is the same problem, and answering it by refusing the whole
+  // `Map` would lose the keys beside it.
+  it('drops a function from a Map, and keeps the rest', () => {
+    const out = toRawDeep({ m: new Map<string, any>([['fn', () => {}], ['kept', 1]]) }, true)
+
+    expect(out.m.has('fn')).toBe(false)
+    expect(out.m.get('kept')).toBe(1)
+  })
+
+  it('drops a marked value from a Set, and keeps the rest', () => {
+    const out = toRawDeep({ s: new Set([markRaw({ heavy: true }), 'kept']) }, true)
+
+    expect([...out.s]).toEqual(['kept'])
+  })
+
+  it('survives a cycle that runs through a Map', () => {
+    const root: Record<string, any> = { name: 'root' }
+    root.m = new Map([['back', root]])
+
+    const out = toRawDeep(root, true)
+
+    expect(out.m.get('back')).toBe(out)
+  })
+})
+
+describe('identity inside one walk', () => {
+  it('gives one Date appearing twice the same copy, as the transport would', () => {
+    const at = new Date(1790071200000)
+
+    const out = toRawDeep({ a: at, b: at }, true)
+
+    expect(out.a).toBe(out.b)
+  })
+})

package/src/app/App.vue

@@ -186,41 +186,50 @@ const storyListVisible = computed(() => !!layoutStore.settings.storyListVisible)
           it. The settings toggles were #596; `isMobile` is a live media query,
           so this one fired on a window resize (#600).
         -->
-        <BaseSplitPane
-          save-id="main-horiz"
-          :min="5"
-          :max="50"
-          :default-split="15"
-          :show-first="!isMobile && storyListVisible"
-          class="flex-1 min-h-0"
-        >
-          <template #first>
-            <div class="flex flex-col h-full bg-gray-100 dark:bg-gray-750 __poveste-pane-shadow-from-right">
-              <AppHeader class="flex-none" />
-              <nav
-                aria-label="Stories"
-                class="flex-1 flex flex-col min-h-0"
-              >
-                <StoryList
-                  :tree="tree"
-                  :stories="stories"
-                  class="flex-1"
+        <!-- `<main>` wraps the split rather than sitting in its last pane. The
+             divider is perceivable now, and it is a sibling of the slot, so it
+             belongs to no landmark unless one contains the whole split. Inside
+             `<main>` the sidebar's `<header>` is a generic header rather than a
+             banner, which is what `landmark-banner-is-top-level` objects to
+             when a landmark is put around that pane instead (#995). -->
+        <main class="flex-1 min-h-0 flex flex-col">
+          <BaseSplitPane
+            save-id="main-horiz"
+            label="Resize the story list"
+            :min="5"
+            :max="50"
+            :default-split="15"
+            :show-first="!isMobile && storyListVisible"
+            class="flex-1 min-h-0"
+          >
+            <template #first>
+              <div class="flex flex-col h-full bg-gray-100 dark:bg-gray-750 __poveste-pane-shadow-from-right">
+                <AppHeader class="flex-none" />
+                <nav
+                  aria-label="Stories"
+                  class="flex-1 flex flex-col min-h-0"
+                >
+                  <StoryList
+                    :tree="tree"
+                    :stories="stories"
+                    class="flex-1"
+                  />
+                </nav>
+              </div>
+            </template>
+
+            <template #last>
+              <div class="flex flex-col h-full">
+                <TopBar
+                  v-if="!isMobile"
+                  @layout="isLayoutOpen = true"
+                  @search="isSearchOpen = true"
                 />
-              </nav>
-            </div>
-          </template>
-
-          <template #last>
-            <main class="flex flex-col h-full">
-              <TopBar
-                v-if="!isMobile"
-                @layout="isLayoutOpen = true"
-                @search="isSearchOpen = true"
-              />
-              <RouterView class="flex-1 min-h-0" />
-            </main>
-          </template>
-        </BaseSplitPane>
+                <RouterView class="flex-1 min-h-0" />
+              </div>
+            </template>
+          </BaseSplitPane>
+        </main>
       </div>
 
       <LayoutModal

package/src/app/components/app/AppActions.vue

@@ -4,7 +4,7 @@ import { computed } from 'vue'
 import { povesteConfig } from '../../util/config'
 import { isDark, toggleDark } from '../../util/dark'
 import { isMobile } from '../../util/responsive'
-import { makeTooltip } from '../../util/tooltip'
+import ShortcutTooltip from './ShortcutTooltip.vue'
 import TopBarChip from './TopBarChip.vue'
 import TopBarChipItem from './TopBarChipItem.vue'
 
@@ -20,41 +20,53 @@ const themeIcon = computed(() => {
 
 <template>
   <TopBarChip>
-    <TopBarChipItem
+    <ShortcutTooltip
       v-if="!isMobile"
-      v-tooltip="makeTooltip('Layout', ({ isMac }) => isMac ? 'meta+shift+l' : 'ctrl+shift+l')"
-      aria-label="Open layout customization"
-      data-testid="layout-btn"
-      @click="$emit('layout')"
+      description="Layout"
+      :shortcut="({ isMac }) => isMac ? 'meta+shift+l' : 'ctrl+shift+l'"
     >
-      <Icon
-        icon="carbon:panel-expansion"
-        class="w-4 h-4"
-      />
-    </TopBarChipItem>
+      <TopBarChipItem
+        aria-label="Open layout customization"
+        data-testid="layout-btn"
+        @click="$emit('layout')"
+      >
+        <Icon
+          icon="carbon:panel-expansion"
+          class="w-4 h-4"
+        />
+      </TopBarChipItem>
+    </ShortcutTooltip>
 
-    <TopBarChipItem
-      v-tooltip="makeTooltip('Search', ({ isMac }) => isMac ? 'meta+k' : 'ctrl+k')"
-      aria-label="Search stories"
-      data-testid="search-btn"
-      @click="$emit('search')"
+    <ShortcutTooltip
+      description="Search"
+      :shortcut="({ isMac }) => isMac ? 'meta+k' : 'ctrl+k'"
     >
-      <Icon
-        icon="carbon:search"
-        class="w-4 h-4"
-      />
-    </TopBarChipItem>
+      <TopBarChipItem
+        aria-label="Search stories"
+        data-testid="search-btn"
+        @click="$emit('search')"
+      >
+        <Icon
+          icon="carbon:search"
+          class="w-4 h-4"
+        />
+      </TopBarChipItem>
+    </ShortcutTooltip>
 
-    <TopBarChipItem
+    <ShortcutTooltip
       v-if="!povesteConfig.theme.hideColorSchemeSwitch"
-      v-tooltip="makeTooltip('Toggle dark mode', ({ isMac }) => isMac ? 'meta+shift+d' : 'ctrl+shift+d')"
-      aria-label="Toggle dark mode"
-      @click="toggleDark()"
+      description="Toggle dark mode"
+      :shortcut="({ isMac }) => isMac ? 'meta+shift+d' : 'ctrl+shift+d'"
     >
-      <Icon
-        :icon="themeIcon"
-        class="w-4 h-4"
-      />
-    </TopBarChipItem>
+      <TopBarChipItem
+        aria-label="Toggle dark mode"
+        @click="toggleDark()"
+      >
+        <Icon
+          :icon="themeIcon"
+          class="w-4 h-4"
+        />
+      </TopBarChipItem>
+    </ShortcutTooltip>
   </TopBarChip>
 </template>

package/src/app/components/app/ShortcutTooltip.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { HstTooltip } from '@poveste/controls'
+import { computed } from 'vue'
+import { isMac } from '../../util/env'
+import { formatKey } from '../../util/keyboard'
+
+const props = defineProps<{
+  description: string
+  /** This action's shortcut, which differs per platform — `meta+shift+l`. */
+  shortcut: (options: { isMac: boolean }) => string
+}>()
+
+const keys = computed(() => props.shortcut({ isMac }).split('+').map(key => formatKey(key.trim())).join(' '))
+</script>
+
+<template>
+  <!-- Rendered rather than built as an HTML string and handed to `v-html`, which
+       is what the tooltip directive needed and what `util/tooltip.ts` was. -->
+  <HstTooltip>
+    <template #content>
+      <div>{{ description }}</div>
+      <div class="flex items-center gap-1 mt-2 text-sm">
+        <span class="border border-gray-600 px-1 rounded-sm text-gray-400">{{ keys }}</span>
+      </div>
+    </template>
+
+    <slot />
+  </HstTooltip>
+</template>