@archetypeai/ds-cli 0.13.0 → 0.15.0

package/files/AGENTS.md

@@ -70,6 +70,10 @@ Use semantic tokens for anything themed; standard Tailwind for layout.
 - Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
 - Chart series colors: `var(--chart-1)` … `var(--chart-5)`
 - Radius on interactive elements: `rounded-interactive`
+- Scrollbars are owned by the theme (`--scrollbar`, `--scrollbar-track`,
+  `--scrollbar-width`). Every `overflow-*` container is already on-brand in both
+  themes — write no scrollbar CSS at all. `bg-scrollbar` exists for a
+  custom-rendered thumb
 
 Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
 layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
@@ -169,4 +173,8 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
+  `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
+  `scrollbar-*` locally also silently disables the webkit pseudo-elements on
+  that element
 - `layerchart` stays pinned exactly

package/files/CLAUDE.md

@@ -70,6 +70,10 @@ Use semantic tokens for anything themed; standard Tailwind for layout.
 - Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
 - Chart series colors: `var(--chart-1)` … `var(--chart-5)`
 - Radius on interactive elements: `rounded-interactive`
+- Scrollbars are owned by the theme (`--scrollbar`, `--scrollbar-track`,
+  `--scrollbar-width`). Every `overflow-*` container is already on-brand in both
+  themes — write no scrollbar CSS at all. `bg-scrollbar` exists for a
+  custom-rendered thumb
 
 Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
 layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
@@ -169,4 +173,8 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
+  `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
+  `scrollbar-*` locally also silently disables the webkit pseudo-elements on
+  that element
 - `layerchart` stays pinned exactly

package/files/ds-manifest.json

@@ -1,6 +1,6 @@
 {
 	"name": "archetypeai-design-system",
-	"version": "0.13.0",
+	"version": "0.15.0",
 	"components": [
 		{
 			"name": "alert",
@@ -38,6 +38,39 @@
 				"`<AspectRatio ratio={16 / 9}>` wrapping an image, video, or bg-muted placeholder."
 			]
 		},
+		{
+			"name": "avatar",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/avatar",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/avatar.json",
+			"description": "User or entity avatar with an image and an initials fallback.",
+			"usage": [
+				"Always compose Root + Fallback: `Avatar.Root` on its own renders an empty circle. The fallback is what shows while the image loads, when there is no `src`, and when the image 404s — so initials (`{user.name.split(' ').map((p) => p[0]).join('')}`) belong there even when you expect a photo.",
+				"Image: `Avatar.Image src={user.avatarUrl} alt={user.name}` — it is a real `<img>`, so `alt` is yours to pass and a missing one is an accessibility violation. Use the person's name, not \"avatar\".",
+				"Size: `sm` (28px) for dense chrome like the side-nav profile row, `default` (36px) for lists and headers, `lg` (48px) for a profile or detail header. The size lands on `data-size` and the fallback's type scales off it through `group-data-[size=…]/avatar`, so overriding the root's `size-*` by hand desynchronises the two — add a size variant instead.",
+				"Shape: `circle` for people, `squircle` (12px radius at every size) for non-human entities (an org, a workspace, a model) so the two read apart at a glance. The radius is deliberately generous — at `sm` the squircle sits close to a circle, which is the intended look.",
+				"Skipping the loading flash: pass `loadingStatus=\"loaded\"` when the image is already cached or inlined, which shows it immediately instead of flashing the fallback. It is bindable, so `bind:loadingStatus` also reads the outcome (`loading` | `loaded` | `error`) if the caller needs to react to a broken image.",
+				"Stacking (“who is on this session”): a `flex -space-x-2` row plus `*:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:border-0` on the container. The ring is what cuts each avatar out of the one behind it, and it hangs off `data-slot`, so separation stays a container concern rather than a prop. Drop the border in a stack: the root's `border-border` sits just inside the ring, so leaving it on renders a grey rim against a white gap against the next rim, and the overlap reads muddy. Stack images, not initials — the overlap covers each avatar's trailing edge, which a face survives and two letters do not."
+			],
+			"variants": {
+				"avatarVariants": {
+					"axes": {
+						"size": [
+							"sm",
+							"default",
+							"lg"
+						],
+						"shape": [
+							"circle",
+							"squircle"
+						]
+					},
+					"defaults": {
+						"size": "default",
+						"shape": "circle"
+					}
+				}
+			}
+		},
 		{
 			"name": "badge",
 			"import": "@archetypeai/ds-ui-svelte-console/primitives/badge",
@@ -250,6 +283,19 @@
 			"source": "https://design-system-console.archetypeai.workers.dev/r/console-utils.json",
 			"description": "className merge helper cn() (clsx + tailwind-merge with the rounded-interactive extension). Re-exported as $lib/utils in scaffolded apps."
 		},
+		{
+			"name": "copy-button",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/copy-button",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/copy-button.json",
+			"description": "Copy-to-clipboard control that owns its own copied state.",
+			"usage": [
+				"Icon beside a value: `CopyButton value={job.id} label=\"Copy job ID\" title={job.id}` — `label` is the accessible name, so say what is being copied rather than \"Copy\", and pass the full value as `title` whenever the visible text is truncated.",
+				"Value inside the control: pass the value as children (`<CopyButton value={id} label=\"Copy blueprint ID\">{id}</CopyButton>`) and the whole thing becomes one copy target with one hover, instead of a 16px icon beside plain text. The hit area follows automatically — children give the `inline` size, icon-only gives the 36px `icon` size.",
+				"Feedback: a check mark replaces the glyph for 1500ms (`feedbackDuration`) and a toast fires on both success and failure, so a mounted `<Toaster />` is a prerequisite. Pass `toast={false}` where the inline check is feedback enough — a table of IDs, where a toast per copy is noise — and the component announces the copy to screen readers itself instead. `successMessage` / `errorMessage` override the wording; `onCopy(copied)` hooks anything else.",
+				"Inside a row that navigates: `stopPropagation` keeps the click off the row's own handler (and off an enclosing anchor). Reveal-on-hover is the Button axis, `visibility=\"hover\"`, which needs `group` on the row — but not when the value is inside the control, since it would fade the value too.",
+				"Copying without a button: `copyText(text)` is exported from the same subpath for a labelled action that happens to copy (a \"Copy CSV\" button in a dialog footer). It resolves to whether the write landed."
+			]
+		},
 		{
 			"name": "counter",
 			"import": "@archetypeai/ds-ui-svelte-console/primitives/counter",
@@ -258,6 +304,7 @@
 			"usage": [
 				"Count: `Counter value={412}` rolls only the digit places that changed; past 999 it abbreviates (`1.2K`, `123K`, `1.2M`) so it never grows a fifth column, and the exact number stays in its title + accessible label.",
 				"Absent vs zero vs loading: omit the component entirely when there is no count, pass `value={0}` for an empty one, and `value={null}` while it is still loading (reserves the same width so nothing reflows when it arrives).",
+				"At least, for a list you cannot size: `Counter value={103} atLeast` renders `103+` when the caller has loaded 103 rows and knows only that more exist (keyset pagination, a capped query). The number is the caller's own, not a rounded threshold, and the accessible label reads \"at least 103\". Past 999 the abbreviation truncates instead of rounding, so `1250` shows `1.2K+` and never claims rows nobody loaded. `atLeast` is ignored on `value={0}`, where it would state nothing.",
 				"Tone & size: `tone=\"muted\"` for a quieter pill against busy chrome; `size=\"sm\"` for dense rows (tables, list items). Inside a tab strip use `Tabs.Count`, which re-colors it for the active/inactive trigger."
 			],
 			"variants": {
@@ -707,11 +754,17 @@
 			"source": "https://design-system-labs.archetypeai.workers.dev/r/logo.json",
 			"description": "Archetype AI brand logo mark.",
 			"usage": [
-				"Headers: `<Logo class=\"h-6 w-auto\" />` next to the app title; sizes sm | default | lg."
+				"Headers: `<Logo class=\"h-6 w-auto\" />` next to the app title; sizes sm | default | lg.",
+				"Compact lockup: `variant=\"compact\"` is the stacked social/avatar artwork (~1.6:1 instead of the wordmark's ~5.4:1). Use it where a horizontal wordmark will not fit — square tiles, avatars, narrow sidebars, splash marks. Defaults to `variant=\"default\"`.",
+				"Sizing is shared: both variants honour size sm | default | lg (h-4 | h-6 | h-8) and take their width from the artwork aspect, so compact renders far narrower at the same height. Prefer default or lg for compact."
 			],
 			"variants": {
 				"logoVariants": {
 					"axes": {
+						"variant": [
+							"default",
+							"compact"
+						],
 						"size": [
 							"sm",
 							"default",
@@ -719,6 +772,7 @@
 						]
 					},
 					"defaults": {
+						"variant": "default",
 						"size": "default"
 					}
 				}
@@ -967,7 +1021,8 @@
 				"Icon view toggle (list/grid): `Tabs.List variant=\"toggle\"` + `Tabs.Trigger variant=\"icon\"` with an icon + title.",
 				"Segmented source switch (Library | File IDs | Upload): `variant=\"toggle\"` list + triggers `size=\"pill\" typography=\"mono\"`.",
 				"Page-section tabs (Progress | Logs | Artifacts): `Tabs.List variant=\"line\"` with plain text triggers; always `Tabs.Root bind:value`.",
-				"Count on a trigger: `<Tabs.Trigger value=\"logs\">Logs <Tabs.Count value={logCount} /></Tabs.Trigger>` — an odometer pill that abbreviates past 999 (`1.2K`) so the strip never reflows. Pass `value={null}` while the count is still loading (it reserves the width), `value={0}` for an empty tab, and omit `Tabs.Count` entirely for a tab that has no count at all."
+				"Count on a trigger: `<Tabs.Trigger value=\"logs\">Logs <Tabs.Count value={logCount} /></Tabs.Trigger>` — an odometer pill that abbreviates past 999 (`1.2K`) so the strip never reflows. Pass `value={null}` while the count is still loading (it reserves the width), `value={0}` for an empty tab, and omit `Tabs.Count` entirely for a tab that has no count at all.",
+				"Count on a tab that cannot be sized: `<Tabs.Count value={loaded} atLeast />` renders `103+` for a keyset-paginated tab that knows only how many rows it has so far. Prefer it over dropping the count entirely, which reads as \"none\"."
 			],
 			"variants": {
 				"tabsListVariants": {
@@ -1072,8 +1127,11 @@
 			"description": "Hover hint.",
 			"usage": [
 				"Wrap the app/section in `Tooltip.Provider delayDuration={200}`.",
-				"Field help: `Tooltip.Trigger variant=\"info\"` holding an InfoIcon placed next to a Label sectionHeader, explanation in Tooltip.Content.",
-				"`variant=\"inlineLink\"` — underlined trigger flowing inside prose (supported file requirements)."
+				"Field help: `Tooltip.Trigger variant=\"info\"` is a filled 20px disc holding a mono `i` — pass it no children, it renders its own glyph. Explanation goes in `Tooltip.Content`.",
+				"`aria-label` on the info trigger is required and is the caller's: name what is being explained (`aria-label=\"About Detection Log\"`). The glyph is `aria-hidden`, so without a label the button has no accessible name.",
+				"The info disc squares against `Counter`'s height on purpose — a list title, its `Counter` and its info disc in one `flex items-center gap-2` row is the intended cluster, the solid pill reading as the count and the muted one as the meaning.",
+				"`variant=\"inlineLink\"` — underlined trigger flowing inside prose (supported file requirements).",
+				"The arrow centres itself on the trigger on all four sides and protrudes half its box — `arrowClasses` is for its ink or size, not for centring corrections. If a tip looks off, it is a bug in `tooltipArrowVariants`, not something to counter-shift at the call site."
 			],
 			"variants": {
 				"tooltipTriggerVariants": {
@@ -1094,9 +1152,16 @@
 			"name": "video-player",
 			"import": "@archetypeai/ds-ui-svelte-labs/primitives/video-player",
 			"source": "https://design-system-labs.archetypeai.workers.dev/r/video-player.json",
-			"description": "Media-playback card with controls and aspect ratio; composes Card + AspectRatio + Button + Slider.",
+			"description": "Media-playback card whose seek track doubles as a timeline: named marker windows, tinted highlight bands and bindable playback state. Composes Card + AspectRatio + Button + Slider.",
 			"usage": [
-				"`<VideoPlayer src muted />` for the standard controlled player; `controls={false}` for ambient/looping footage."
+				"`<VideoPlayer src muted />` for the standard controlled player; `controls={false}` for ambient/looping footage. `preload=\"metadata\"` by default, so `duration` is known before the first play.",
+				"Playback state: `bind:time` / `bind:duration` / `bind:paused` mirror the media element out, and `time` and `paused` are writable - assigning to `time` seeks, assigning `paused = false` plays. That is how another view drives the player.",
+				"Markers: `markers={[{ start, end, label?, color? }]}` in **seconds, not fractions** draws one focusable dot per window on the seek track. Clicking a dot expands it into a range pill, seeks to its start and plays; one is expanded at a time, and `bind:activeMarker` is its index (or null). Scrubbing by hand, or a click on the video surface, collapses it. `loopActiveMarker` loops playback inside the expanded window.",
+				"Linked brushing: `highlights={[{ start, end, color? }]}` tints regions another view is pointing at (brushing in), and `onMarkerHover(index | null)` fires on hover **and focus** so a hovered marker can highlight the matching row elsewhere (brushing out).",
+				"Two lifecycle traps when `src` changes: a new `src` remounts the player and Svelte's media bindings write your bound values into the fresh element, so reset `time = 0` and `paused = true` yourself or a stale position becomes the new clip's start; and `bind:duration` holds the previous clip's value until `loadedmetadata`, so reseed `duration` from a known length if marker geometry must be right on the first frame (`duration === 0` collapses every marker to the left edge).",
+				"`controlsVisibility=\"always\"` pins the control bar open - required whenever markers must stay clickable during playback, since the default `\"auto\"` fades the bar (and the markers with it) 2.5s into playback. `formatTime` replaces the mm:ss clock in the time readout and the marker captions.",
+				"Style hooks: `data-slot` on `video-player`, `-video`, `-overlay`, `-controls`, `-time`, `-markers`, `-marker` (carries `data-expanded`), `-marker-caption`, `-highlight`. A per-marker `color` inks the outline and fill via `currentColor`.",
+				"Marker seeking needs an origin that serves HTTP Range requests; against one that does not, seeks silently do nothing (serve the clip from a blob URL instead)."
 			],
 			"variants": {
 				"videoPlayerOverlayVariants": {
@@ -1120,6 +1185,28 @@
 					"defaults": {
 						"visible": "true"
 					}
+				},
+				"videoPlayerMarkerVariants": {
+					"axes": {
+						"expanded": [
+							"true",
+							"false"
+						],
+						"filled": [
+							"true",
+							"false"
+						],
+						"emphasis": [
+							"hidden",
+							"full",
+							"ambient"
+						]
+					},
+					"defaults": {
+						"expanded": "false",
+						"filled": "false",
+						"emphasis": "ambient"
+					}
 				}
 			}
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archetypeai/ds-cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Archetype AI Design System CLI Tool",
   "type": "module",
   "bin": {