@heyramzi/ui 0.0.0-stage → 1.53.0

package/COMPONENTS.md

@@ -0,0 +1,133 @@
+# Components
+
+Every component in `@heyramzi/ui`, one line each. Import a component from its subpath, e.g.
+`import { Button } from "@heyramzi/ui/shadcn/button"`.
+
+The style layer lives in [`src/tokens.css`](./src/tokens.css) and the motion CSS in
+[`src/animations`](./src/animations). Components that already exist in
+[shadcn-svelte](https://shadcn-svelte.com) are linked there from the root README.
+
+## shadcn primitives (`src/shadcn`)
+
+- `accordion` — Accordion
+- `alert` — alertVariants, AlertVariant
+- `alert-dialog` — AlertDialog
+- `attachment` — Attachment
+- `avatar` — Avatar
+- `badge` — Badge, badgeVariants, BadgeVariant
+- `breadcrumb` — Breadcrumb
+- `bubble` — Bubble
+- `button` — Button
+- `calendar` — Calendar
+- `card` — Card
+- `checkbox` — Checkbox
+- `code-block` — CodeBlock. Highlight with `useHighlightedCode` from `@heyramzi/ui/shadcn/hooks/use-highlighted-code.svelte` (Shiki, ANSI too)
+- `collapsible` — Collapsible
+- `command` — Command, computeCommandScore (the scorer, for a custom `filter`)
+- `context-menu` — ContextMenu
+- `dialog` — Dialog
+- `dropdown-menu` — CheckboxGroup, CheckboxItem, Content, Portal, DropdownMenu, DropdownMenuCheckboxGroup
+- `empty` — Empty
+- `field` — Field and its parts, plus SimpleField: label, hint or error and the control, with the message linked by `aria-describedby`
+- `hover-card` — HoverCard
+- `input` — Input
+- `input-otp` — InputOtp
+- `label` — Label
+- `marker` — Marker
+- `message` — Message
+- `message-scroller` — MessageScroller, the chat transcript scroller: follows a streamed reply, anchors each turn, keeps place on prepend
+- `popover` — Popover
+- `progress` — Progress
+- `radio-group` — RadioGroup
+- `scroll-area` — ScrollArea
+- `select` — Select
+- `separator` — Separator
+- `sheet` — Sheet (`side`: `left`, `right` or `bottom`)
+- `sidebar` — Sidebar
+- `skeleton` — Skeleton
+- `slider` — Slider
+- `sonner` — Toaster
+- `spinner` — Spinner
+- `switch` — Switch
+- `table` — Table
+- `tabs` — Tabs
+- `textarea` — Textarea
+- `toggle` — toggleVariants, ToggleSize, ToggleVariant, ToggleVariants
+- `toggle-group` — ToggleGroup
+- `tooltip` — Tooltip
+- `trace` — Trace, an agent's steps: reasoning, tool calls and sources as status rows that can expand
+
+## Components (`src/components`)
+
+Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<name>`.
+
+- `copy` — CopyButton, copyText, copyRichText, htmlToPlainText, Copied
+- `data-table` — SortableHead, Pagination, InfiniteScroll, RowContextMenu, TableSkeleton, and the sort, page and filter helpers
+- `hold-to-confirm` — HoldToConfirm, press and hold to confirm
+- `icon` — Icon, a Phosphor component at a size
+- `language-flag` — LanguageFlag
+- `list-page` — ListPageShell, MasterDetail, GroupedList, RailRow and the rest of the master-detail page kit, NoticeBar, EmptyState, FilterPopover, setSectionHost
+- `locale-switch` — LocaleSwitch, a language switch on SegmentedFilter
+- `mark` — Mark, a logo or photo glyph with an initial fallback
+- `open-in` — OpenIn, a link out to a tool that takes the tool's name, label and mark as a prop
+- `picker` — Picker, MarkPicker, pickerTriggerClass, a command palette at popover scale
+- `segmented` — AnimatedTabs (pill or underline), SegmentedFilter, SegmentedNav, SectionRuns, one bordered track with a sliding pill, a badge note and an overflow menu
+- `star-rating-input` — StarRatingInput
+- `svg` — Svg, an SVG file imported with `?raw`
+
+## Effects (`src/effects`)
+
+- `interactive-hover-button` — InteractiveHoverButton, a dot that grows into the fill
+
+- `animated-beam` — AnimatedBeam, AnimatedBeamProps, AnchorPosition
+- `border-beam` — BorderBeam
+- `image-comparison` — ImageComparison, a before/after wipe with a bindable position, side badges and a hint sweep
+- `image-reveal` — ImageReveal, ImageRevealProps, ImageRevealHandle
+- `magnetic` — magnetic
+- `magic-card` — MagicCard. Props: `glow`, `radius`, `class`, `contentClass`; the glow colour is `--magic-card-glow` set on `class`.
+- `marquee` — Marquee
+- `progressive-blur` — ProgressiveBlur
+- `reveal` — InView, AnimatedGroup, TextEffect, observeInView, RevealPreset, RevealPer
+- `shader-gradient` — ShaderGradient, ShaderGradientProps, ShaderGradientUniforms
+- `spotlight` — Spotlight
+- `theme-toggle` — ThemeToggle, revealTheme. Props: `isDark`, `mode` (`light`, `dark`, `system`; swaps in the Monitor icon), `onToggle`, `variant` (`outline`, `ghost`, `inverted`, `slide`; `inverted` boolean is an alias; `slide` is a pill with a moving thumb, coloured by `--theme-toggle-thumb-light`, `--theme-toggle-thumb-dark`, `--theme-toggle-track`, `--theme-toggle-glow` and friends set on `class`), `size`, `label`, `title`, `skipTransition`, `class`. `revealTheme(event, apply, { skip, duration, easing })` is the circular wipe on its own: `import { revealTheme } from "@heyramzi/ui"` (the `./lib/*` subpath points at `.js` and the source is `.ts`).
+
+## Animations (`src/animations`)
+
+- `avatar-group-hover` — keyframe utilities
+- `card-tilt` — keyframe utilities
+- `digit-pop-in` — keyframe utilities
+- `dropdown` — keyframe utilities
+- `input-clear-dissolve` — keyframe utilities
+- `input-shake` — keyframe utilities
+- `learn-more-hover` — keyframe utilities
+- `like-button` — keyframe utilities
+- `modal` — keyframe utilities
+- `page-side-by-side` — keyframe utilities
+- `plus-menu-morph` — keyframe utilities
+- `resize` — keyframe utilities
+- `shimmer-text` — keyframe utilities
+- `spinning-counter` — keyframe utilities
+- `success-check` — keyframe utilities
+- `text-swap` — keyframe utilities
+- `thinking-states` — keyframe utilities
+
+## AI and chat (`src/ai`)
+
+- `ai-button` — AiButton
+- `confirmation` — Confirmation, ConfirmationTitle, ConfirmationRequest, ConfirmationAccepted, ConfirmationRejected, ConfirmationActions, ConfirmationAction
+- `generation-progress` — GenerationProgress
+- `loading-state` — PixelLoader
+- `prompt-input` — PromptInput, PromptInputBody, PromptInputToolbar, PromptInputTextarea, PromptInputSubmit
+- `reasoning` — Reasoning, ReasoningTrigger, ReasoningContent
+- `response` — Response
+- `suggestion` — Suggestion, Suggestions
+- `thinking-dots` — ThinkingDots
+- `typing-dots` — TypingDots
+- `voice-waveform` — VoiceWaveform
+
+---
+
+Skipped on purpose: brand assets (logos, marks, brand renderer), kanban, list, gantt and status (they live in `@heyramzi/tasks`), and charts
+(they live in `@heyramzi/charts`). The bot avatars
+are in `src/agents`, imported from `@heyramzi/ui/agents`.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @heyramzi/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 UI primitives you copy into your project and own. Components, visual
+effects, CSS animations and a small set of chat and AI surfaces. No build step, no runtime wrapper,
+no framework lock-in.
+
+The package is a source registry. Every component is a folder under
+`src/` that you can copy into your own `$lib` and edit. The root barrel is
+only a convenience.
+
+## What is inside
+
+- `src/shadcn` shadcn-svelte primitives, generalized.
+- `src/components` generic pieces on the primitives: segmented control, picker, copy button, data table, list page, hold to confirm and more.
+- `src/effects` animated borders, beams, marquee, spotlight, image reveal,
+  image comparison, shimmer gradients and a theme toggle.
+- `src/animations` keyframe CSS for dropdowns, modals, tooltips, text swaps,
+  success checks and the rest of the motion vocabulary.
+- `src/ai` chat and AI surfaces: prompt input, response, reasoning, confirmation and loaders.
+- `src/agents` bot avatars and a cast grid, imported from `@heyramzi/ui/agents`:
+  `AgentAvatar` draws an eyes-only face from a name, role, shape and colour, and
+  `AgentCast` lays a list of agents out as cards you can pick from.
+
+See [COMPONENTS.md](./COMPONENTS.md) for the full list, one line each.
+
+## Setup
+
+Import the style layer once, after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@heyramzi/ui/tokens.css";
+@import "@heyramzi/ui/animations";
+```
+
+`tokens.css` carries the palette, the semantic tokens and the craft layer
+(radius, elevation, focus, motion). `animations` carries the keyframes the
+components reference. If you use the Attachment or Message component, also
+import `@heyramzi/ui/shadcn/utilities.css`.
+
+Retheme by overriding any variable on `:root`, for example
+`--color-brand-indigo` or `--radius-lg`. Dark mode keys off a `.dark`
+class on `html`.
+
+Rich text lives in [`@heyramzi/rich-editor`](https://github.com/heyramzi/ui/tree/main/packages/rich-editor),
+so the kit doesn't pull Tiptap into every app.
+
+Charts live in their own package now,
+[`@heyramzi/charts`](https://github.com/heyramzi/ui/tree/main/packages/charts). It reads
+the same tokens, so import `tokens.css` once and both work.
+
+React and other framework ports are out of scope. The source is Svelte 5
+runes only.
+
+## Using a component
+
+Import from a subpath:
+
+```svelte
+<script lang="ts">
+  import { Button } from "@heyramzi/ui/shadcn/button";
+  import { Card, CardHeader, CardTitle, CardContent } from "@heyramzi/ui/shadcn/card";
+  import Marquee from "@heyramzi/ui/effects/marquee/Marquee.svelte";
+</script>
+```
+
+Many components take their content through snippets, so you keep full control:
+
+```svelte
+<Button variant="outline" size="sm" onclick={save}>Save</Button>
+```
+
+## shadcn-svelte
+
+The primitives in `src/shadcn` are copies of
+[shadcn-svelte](https://shadcn-svelte.com), generalized. If a component exists
+there, use its page for props and examples:
+
+| Component | Docs |
+| --- | --- |
+| `accordion` | https://shadcn-svelte.com/docs/components/accordion |
+| `alert` | https://shadcn-svelte.com/docs/components/alert |
+| `alert-dialog` | https://shadcn-svelte.com/docs/components/alert-dialog |
+| `attachment` | https://shadcn-svelte.com/docs/components/attachment |
+| `avatar` | https://shadcn-svelte.com/docs/components/avatar |
+| `badge` | https://shadcn-svelte.com/docs/components/badge |
+| `breadcrumb` | https://shadcn-svelte.com/docs/components/breadcrumb |
+| `bubble` | https://shadcn-svelte.com/docs/components/bubble |
+| `button` | https://shadcn-svelte.com/docs/components/button |
+| `calendar` | https://shadcn-svelte.com/docs/components/calendar |
+| `card` | https://shadcn-svelte.com/docs/components/card |
+| `checkbox` | https://shadcn-svelte.com/docs/components/checkbox |
+| `collapsible` | https://shadcn-svelte.com/docs/components/collapsible |
+| `command` | https://shadcn-svelte.com/docs/components/command |
+| `context-menu` | https://shadcn-svelte.com/docs/components/context-menu |
+| `dialog` | https://shadcn-svelte.com/docs/components/dialog |
+| `dropdown-menu` | https://shadcn-svelte.com/docs/components/dropdown-menu |
+| `empty` | https://shadcn-svelte.com/docs/components/empty |
+| `field` | https://shadcn-svelte.com/docs/components/field |
+| `hover-card` | https://shadcn-svelte.com/docs/components/hover-card |
+| `input` | https://shadcn-svelte.com/docs/components/input |
+| `input-otp` | https://shadcn-svelte.com/docs/components/input-otp |
+| `label` | https://shadcn-svelte.com/docs/components/label |
+| `marker` | https://shadcn-svelte.com/docs/components/marker |
+| `message` | https://shadcn-svelte.com/docs/components/message |
+| `popover` | https://shadcn-svelte.com/docs/components/popover |
+| `progress` | https://shadcn-svelte.com/docs/components/progress |
+| `radio-group` | https://shadcn-svelte.com/docs/components/radio-group |
+| `scroll-area` | https://shadcn-svelte.com/docs/components/scroll-area |
+| `select` | https://shadcn-svelte.com/docs/components/select |
+| `separator` | https://shadcn-svelte.com/docs/components/separator |
+| `sheet` | https://shadcn-svelte.com/docs/components/sheet |
+| `sidebar` | https://shadcn-svelte.com/docs/components/sidebar |
+| `skeleton` | https://shadcn-svelte.com/docs/components/skeleton |
+| `slider` | https://shadcn-svelte.com/docs/components/slider |
+| `sonner` | https://shadcn-svelte.com/docs/components/sonner |
+| `spinner` | https://shadcn-svelte.com/docs/components/spinner |
+| `switch` | https://shadcn-svelte.com/docs/components/switch |
+| `table` | https://shadcn-svelte.com/docs/components/table |
+| `tabs` | https://shadcn-svelte.com/docs/components/tabs |
+| `textarea` | https://shadcn-svelte.com/docs/components/textarea |
+| `toggle` | https://shadcn-svelte.com/docs/components/toggle |
+| `toggle-group` | https://shadcn-svelte.com/docs/components/toggle-group |
+| `tooltip` | https://shadcn-svelte.com/docs/components/tooltip |
+
+## Credits
+
+Inspired by [shadcn-svelte](https://github.com/huntabyte/shadcn-svelte).
+The reveal, marquee and beam effects are inspired by
+[motion-primitives](https://github.com/ibelick/motion-primitives), and the
+motion vocabulary by [transitions-dev](https://transitions.dev). The agent avatars
+port [bot-avatars](https://github.com/Jakubantalik/Libraries.dev/tree/main/packages/bot-avatars) 0.2.2; its licence is in
+`src/agents/vendor/LICENSE`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,220 @@
 {
   "name": "@heyramzi/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.53.0",
+  "description": "Svelte 5 UI primitives: effects, animations, and shared component CSS.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heyramzi/ui.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://ui.heyramzi.com",
+  "type": "module",
+  "svelte": "./src/index.ts",
+  "files": [
+    "src",
+    "scripts",
+    "package.json",
+    "README.md",
+    "COMPONENTS.md"
+  ],
+  "imports": {
+    "#scripts/*": "./scripts/*",
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "svelte": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./tokens.css": "./src/tokens.css",
+    "./lib/*.js": {
+      "svelte": "./src/lib/*.ts",
+      "types": "./src/lib/*.ts",
+      "default": "./src/lib/*.ts"
+    },
+    "./lib/*": {
+      "svelte": "./src/lib/*.ts",
+      "types": "./src/lib/*.ts",
+      "default": "./src/lib/*.ts"
+    },
+    "./border-beam": {
+      "svelte": "./src/effects/border-beam/BorderBeam.svelte",
+      "default": "./src/effects/border-beam/BorderBeam.svelte"
+    },
+    "./effects/border-beam": {
+      "svelte": "./src/effects/border-beam/BorderBeam.svelte",
+      "default": "./src/effects/border-beam/BorderBeam.svelte"
+    },
+    "./theme-toggle": {
+      "svelte": "./src/effects/theme-toggle/ThemeToggle.svelte",
+      "default": "./src/effects/theme-toggle/ThemeToggle.svelte"
+    },
+    "./effects/theme-toggle": {
+      "svelte": "./src/effects/theme-toggle/ThemeToggle.svelte",
+      "default": "./src/effects/theme-toggle/ThemeToggle.svelte"
+    },
+    "./effects/animated-beam": {
+      "svelte": "./src/effects/animated-beam/index.ts",
+      "types": "./src/effects/animated-beam/index.ts",
+      "default": "./src/effects/animated-beam/index.ts"
+    },
+    "./effects/spotlight": {
+      "svelte": "./src/effects/spotlight/Spotlight.svelte",
+      "default": "./src/effects/spotlight/Spotlight.svelte"
+    },
+    "./effects/magic-card": {
+      "svelte": "./src/effects/magic-card/MagicCard.svelte",
+      "default": "./src/effects/magic-card/MagicCard.svelte"
+    },
+    "./effects/marquee": {
+      "svelte": "./src/effects/marquee/Marquee.svelte",
+      "default": "./src/effects/marquee/Marquee.svelte"
+    },
+    "./effects/image-reveal": {
+      "svelte": "./src/effects/image-reveal/index.ts",
+      "types": "./src/effects/image-reveal/index.ts",
+      "default": "./src/effects/image-reveal/index.ts"
+    },
+    "./effects/shader-gradient": {
+      "svelte": "./src/effects/shader-gradient/index.ts",
+      "types": "./src/effects/shader-gradient/index.ts",
+      "default": "./src/effects/shader-gradient/index.ts"
+    },
+    "./effects/reveal": {
+      "svelte": "./src/effects/reveal/index.ts",
+      "types": "./src/effects/reveal/index.ts",
+      "default": "./src/effects/reveal/index.ts"
+    },
+    "./effects/progressive-blur": {
+      "svelte": "./src/effects/progressive-blur/ProgressiveBlur.svelte",
+      "default": "./src/effects/progressive-blur/ProgressiveBlur.svelte"
+    },
+    "./effects/interactive-hover-button": {
+      "svelte": "./src/effects/interactive-hover-button/InteractiveHoverButton.svelte",
+      "default": "./src/effects/interactive-hover-button/InteractiveHoverButton.svelte"
+    },
+    "./effects/image-comparison": {
+      "svelte": "./src/effects/image-comparison/ImageComparison.svelte",
+      "default": "./src/effects/image-comparison/ImageComparison.svelte"
+    },
+    "./effects/magnetic": {
+      "svelte": "./src/effects/magnetic/magnetic.ts",
+      "types": "./src/effects/magnetic/magnetic.ts",
+      "default": "./src/effects/magnetic/magnetic.ts"
+    },
+    "./icons/sf-symbols": {
+      "svelte": "./src/icons/sf-symbols.ts",
+      "types": "./src/icons/sf-symbols.ts",
+      "default": "./src/icons/sf-symbols.ts"
+    },
+    "./icons/trades": {
+      "svelte": "./src/icons/trades.ts",
+      "types": "./src/icons/trades.ts",
+      "default": "./src/icons/trades.ts"
+    },
+    "./icons/TradeIcon": {
+      "svelte": "./src/icons/TradeIcon.svelte",
+      "default": "./src/icons/TradeIcon.svelte"
+    },
+    "./design": {
+      "style": "./src/design/index.css",
+      "default": "./src/design/index.css"
+    },
+    "./animations": {
+      "style": "./src/animations/index.css",
+      "default": "./src/animations/index.css"
+    },
+    "./animations/text-swap": {
+      "default": "./src/animations/text-swap.ts"
+    },
+    "./animations/*": {
+      "default": "./src/animations/*"
+    },
+    "./shadcn/hooks/*": {
+      "svelte": "./src/shadcn/hooks/*.ts",
+      "types": "./src/shadcn/hooks/*.ts",
+      "default": "./src/shadcn/hooks/*.ts"
+    },
+    "./shadcn/*": {
+      "svelte": "./src/shadcn/*/index.ts",
+      "types": "./src/shadcn/*/index.ts",
+      "default": "./src/shadcn/*/index.ts"
+    },
+    "./components/*": {
+      "svelte": "./src/components/*/index.ts",
+      "types": "./src/components/*/index.ts",
+      "default": "./src/components/*/index.ts"
+    },
+    "./shadcn/utilities.css": {
+      "style": "./src/shadcn/utilities.css",
+      "default": "./src/shadcn/utilities.css"
+    },
+    "./ai": {
+      "svelte": "./src/ai/index.ts",
+      "types": "./src/ai/index.ts",
+      "default": "./src/ai/index.ts"
+    },
+    "./ai/*": {
+      "svelte": "./src/ai/*/index.ts",
+      "types": "./src/ai/*/index.ts",
+      "default": "./src/ai/*/index.ts"
+    },
+    "./agents": {
+      "svelte": "./src/agents/index.ts",
+      "types": "./src/agents/index.ts",
+      "default": "./src/agents/index.ts"
+    },
+    "./agents/demo.svelte": "./src/agents/demo.svelte"
+  },
+  "dependencies": {
+    "@heyramzi/utils": "^1.8.1",
+    "@shadcn-svelte/primitives": "^0.0.1",
+    "marked": "^18.1.0",
+    "phosphor-svelte": "^3.1.0",
+    "shiki": "^4.5.0",
+    "tailwind-variants": "^3.3.1"
+  },
+  "devDependencies": {
+    "@internationalized/date": "^3.12.4",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@types/node": "^26.6.4",
+    "bits-ui": "^2.19.5",
+    "jsdom": "^30.1.2",
+    "mode-watcher": "^1.1.0",
+    "svelte": "^5.57.2",
+    "svelte-sonner": "^1.2.1",
+    "vite-plus": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "peerDependencies": {
+    "@internationalized/date": "^3.12.4",
+    "@tabler/icons-svelte-runes": "^3.46.0",
+    "bits-ui": "^2.19.5",
+    "mode-watcher": "^1.1.0",
+    "svelte": "^5.57.2",
+    "svelte-sonner": "^1.2.1"
+  },
+  "peerDependenciesMeta": {
+    "mode-watcher": {
+      "optional": true
+    },
+    "svelte-sonner": {
+      "optional": true
+    },
+    "@internationalized/date": {
+      "optional": true
+    },
+    "@tabler/icons-svelte-runes": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vp test run",
+    "sync:transitions": "node scripts/sync-transitions.mjs",
+    "sync:shadcn": "node scripts/sync-shadcn.mjs",
+    "sync": "pnpm sync:transitions && pnpm sync:shadcn",
+    "sync:check": "node scripts/sync-transitions.mjs --check && node scripts/sync-shadcn.mjs --check"
+  }
 }

package/scripts/lib/sync-core.mjs

@@ -0,0 +1,113 @@
+/* Shared plumbing for the two upstream sync scripts. `.upstream/` holds the
+ * pristine copy each one diffs against. See ../../docs/decisions.md. */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export const CHECK = process.argv.includes("--check");
+
+export function sha256(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+const get = (url) => fetch(url, { headers: { "user-agent": "heyramzi-ui-sync" } });
+
+export async function fetchText(url) {
+  const res = await get(url);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText} — ${url}`);
+  return await res.text();
+}
+
+/** null instead of a throw, for an upstream file that may not exist. */
+export async function fetchTextIf(url) {
+  const res = await get(url);
+  return res.ok ? await res.text() : null;
+}
+
+export async function fetchJson(url) {
+  return JSON.parse(await fetchText(url));
+}
+
+/** Resolve the upstream commit a sync pinned, so the lock names a point in history. */
+export async function githubHeadSha(repo, branch = "main") {
+  const res = await fetch(`https://api.github.com/repos/${repo}/commits/${branch}`, {
+    headers: { accept: "application/vnd.github.sha", "user-agent": "heyramzi-ui-sync" },
+  });
+  return res.ok ? (await res.text()).trim() : null;
+}
+
+/* Formatting is not divergence: oxfmt reflows prettier wraps and adds
+ * its missing trailing comma, so norm strips both before comparing. */
+const norm = (text) =>
+  text
+    .replace(/,(\s*[)\]}>])/g, "$1")
+    .replace(/\s+(\/?>)/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim();
+
+/**
+ * Where our copy stands against `base`, the content the last sync vendored, and
+ * `next`, what upstream ships now. Both already adapted to this package.
+ */
+export function classify(local, base, next) {
+  if (local === null) return base === null ? "new" : "dropped";
+  if (norm(local) === norm(next)) return "current";
+  if (base !== null && norm(local) === norm(base)) return "stale";
+  return "diverged";
+}
+
+export async function readLock(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeFileDeep(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+}
+
+export async function removeDeep(path) {
+  await rm(path, { recursive: true, force: true });
+}
+
+/** Run `fn` over `items` with at most `limit` in flight. */
+export async function mapLimit(items, limit, fn) {
+  const out = Array.from({ length: items.length });
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (next < items.length) {
+        const i = next++;
+        out[i] = await fn(items[i], i);
+      }
+    }),
+  );
+  return out;
+}
+
+const BULLET = { added: "+", changed: "~", removed: "-", unported: "!", synced: "*", port: "!" };
+
+/** Print the buckets and exit non-zero under --check when any is non-empty. */
+export function report({ title, buckets, unchanged, footer, trailer }) {
+  const lines = [];
+  for (const [kind, items] of Object.entries(buckets)) {
+    for (const item of items) lines.push(`  ${BULLET[kind] ?? "?"} ${kind.padEnd(9)} ${item}`);
+  }
+  console.log(`\n${title}`);
+  console.log(lines.length ? lines.join("\n") : "  = in sync");
+  console.log(`  ${unchanged} unchanged${footer ? `, ${footer}` : ""}`);
+
+  if (!lines.length) return 0;
+  if (CHECK) {
+    console.error("\n  --check: upstream moved. Run the sync without --check and port the diff.");
+    return 1;
+  }
+  console.log(
+    `\n  ${trailer ?? "Vendored copies updated. Review `git diff .upstream/` and port by hand."}`,
+  );
+  return 0;
+}

package/scripts/relative-imports.mjs

@@ -0,0 +1,39 @@
+// Rewrites every `#src/` and `#scripts/` specifier to a relative path, in place, before publish.
+// WHY: Vite cannot resolve a package's own `#` imports inside node_modules (ai-doc/references/publishing-packages.md).
+// It edits the source tree, so only scripts/release.sh runs it, right before `pnpm publish`, and restores the tree after.
+// It is not a `build` script: `pnpm -r build` would rewrite the working tree.
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const targets = { src: join(root, "src"), scripts: join(root, "scripts") };
+const TEXT = /\.(ts|js|mjs|svelte|css)$/;
+const SPECIFIER = /(["'`])#(src|scripts)\/([^"'`]+)\1/g;
+
+async function* walk(dir) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(full);
+    else if (TEXT.test(entry.name)) yield full;
+  }
+}
+
+let files = 0;
+let specifiers = 0;
+for (const dir of Object.values(targets)) {
+  for await (const file of walk(dir)) {
+    const text = await readFile(file, "utf8");
+    const next = text.replace(SPECIFIER, (_, quote, base, rest) => {
+      specifiers++;
+      let rel = relative(dirname(file), join(targets[base], rest));
+      if (!rel.startsWith(".")) rel = `./${rel}`;
+      return `${quote}${rel}${quote}`;
+    });
+    if (next !== text) {
+      await writeFile(file, next);
+      files++;
+    }
+  }
+}
+console.log(`relative-imports: ${specifiers} specifiers in ${files} files`);