@mhmo91/schmancy 0.9.28 → 0.10.1

package/src/agent/agent-bundle.test.ts

@@ -2,74 +2,91 @@ import { describe, expect, it } from 'vitest'
 import './agent-entry'
 
 /**
- * Agent bundle = distribution test suite.
+ * Acceptance test per the Claude Design handover §4.4:
  *
- * The bundle exists so consumers can drop a single `<script type="module">`
- * tag and get every `<schmancy-*>` element registered. These tests verify
- * that contract, no more.
+ * > "CI check: load the bundle in a headless browser, assert
+ * > `customElements.get('schmancy-button')` resolves, assert
+ * > `window.schmancy.help()` returns non-empty."
  *
- * Earlier versions of this suite tested a `window.schmancy.help()` /
- * `tokens()` / `findFor()` runtime introspection surface that targeted a
- * hypothetical live-in-browser agent — a consumer that never materialised
- * in any shipping product. That surface was removed; AI consumers read the
- * static manifest at `dist/agent/schmancy.manifest.json` instead, which is
- * the real integration point.
+ * This test is the runtime smoke test. It imports the agent bundle entry
+ * (which side-effect registers every <schmancy-*> tag plus <schmancy-skill>)
+ * and then verifies the self-describing surface is installed.
  */
-describe('agent bundle — distribution', () => {
+describe('agent bundle — handover §4.4 acceptance', () => {
 	it('registers `schmancy-button` on import', () => {
 		expect(customElements.get('schmancy-button')).toBeDefined()
 	})
 
-	it('registers `schmancy-theme` on import', () => {
-		expect(customElements.get('schmancy-theme')).toBeDefined()
+	it('registers `schmancy-skill` on import', () => {
+		expect(customElements.get('schmancy-skill')).toBeDefined()
 	})
 
-	it('registers `schmancy-surface` on import', () => {
-		expect(customElements.get('schmancy-surface')).toBeDefined()
+	it('installs `window.schmancy` when a <schmancy-skill> connects', async () => {
+		const host = document.createElement('div')
+		const skill = document.createElement('schmancy-skill')
+		host.appendChild(skill)
+		document.body.appendChild(host)
+
+		await customElements.whenDefined('schmancy-skill')
+		// One microtask for connectedCallback to finish installing globals.
+		await new Promise(requestAnimationFrame)
+
+		expect(typeof window.schmancy).toBe('object')
+		expect(typeof window.schmancy?.help).toBe('function')
+		expect(typeof window.schmancy?.tokens).toBe('function')
+		expect(typeof window.schmancy?.capabilities).toBe('function')
+
+		host.remove()
 	})
 
-	it('registers a substantive set of components on import', () => {
-		// Spot-check 20 commonly-used tags. If anything below this threshold
-		// regresses, the side-effect registration chain is broken.
-		const sampleTags = [
-			'schmancy-button',
-			'schmancy-input',
-			'schmancy-card',
-			'schmancy-dialog',
-			'schmancy-sheet',
-			'schmancy-list',
-			'schmancy-list-item',
-			'schmancy-typography',
-			'schmancy-icon',
-			'schmancy-icon-button',
-			'schmancy-form',
-			'schmancy-checkbox',
-			'schmancy-select',
-			'schmancy-autocomplete',
-			'schmancy-radio-group',
-			'schmancy-textarea',
-			'schmancy-switch',
-			'schmancy-divider',
-			'schmancy-details',
-			'schmancy-card-content',
-		]
-		const registered = sampleTags.filter(tag => customElements.get(tag) !== undefined)
-		expect(registered).toEqual(sampleTags)
+	it('`window.schmancy.help()` returns a non-empty manifest summary', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const help = window.schmancy!.help() as { elements: unknown[]; services: unknown[] }
+		expect(Array.isArray(help.elements)).toBe(true)
+		expect(help.elements.length).toBeGreaterThan(50)
+
+		skill.remove()
 	})
 
-	it('exports the imperative service surface', async () => {
-		const mod = await import('./agent-entry')
-		expect(typeof mod.$dialog).toBe('object')
-		expect(typeof mod.$notify).toBe('object')
-		expect(typeof mod.sheet).toBe('object')
-		expect(typeof mod.theme).toBe('object')
-		expect(typeof mod.area).toBe('object')
+	it('`window.schmancy.help("schmancy-button")` returns attribute enum values', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const btn = window.schmancy!.help('schmancy-button') as {
+			attributes?: Array<{ name: string; values?: string[] }>
+		}
+		expect(btn).toBeTruthy()
+		expect(btn.attributes?.length ?? 0).toBeGreaterThan(0)
+		const variant = btn.attributes?.find(a => a.name === 'variant')
+		expect(variant?.values).toContain('filled')
+
+		skill.remove()
 	})
 
-	it('does not install the legacy `window.schmancy` runtime surface', () => {
-		// Negative test — the runtime introspection layer was removed
-		// because no shipping consumer used it. If it comes back unintentionally,
-		// flag it here so the regression is visible.
-		expect((window as { schmancy?: unknown }).schmancy).toBeUndefined()
+	it('`window.schmancy.capabilities()` reports every probed feature', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const caps = window.schmancy!.capabilities()
+		expect(caps).toMatchObject({
+			popover: expect.any(Boolean),
+			declarativeShadowDom: expect.any(Boolean),
+			scopedRegistries: expect.any(Boolean),
+			trustedTypes: expect.any(Boolean),
+			cssRegisteredProperties: expect.any(Boolean),
+			elementInternalsAria: expect.any(Boolean),
+			formAssociated: expect.any(Boolean),
+			adoptedStyleSheets: expect.any(Boolean),
+		})
+
+		skill.remove()
 	})
 })

package/src/agent/agent-entry.ts

@@ -1,22 +1,5 @@
-/**
- * Agent bundle entry — the single-URL ESM distribution.
- *
- * Importing this module side-effect-registers every `<schmancy-*>` custom
- * element and exposes the imperative service surface ($dialog, sheet,
- * $notify, etc.). The import is meant for standalone HTML files and
- * one-page demos that want schmancy without a bundler.
- *
- * **Not** an agent-introspection runtime. Earlier versions installed a
- * `window.schmancy` object with `help()` / `tokens()` / `findFor()` for
- * a hypothetical "live agent in a browser" consumer that never materialised
- * in any shipping product. AI consumers (Claude Design's source ingestion,
- * IDE tooling, build pipelines) read the static manifest at
- * `dist/agent/schmancy.manifest.json` — that's the actual integration point.
- *
- * The bundle stays as a distribution convenience; the runtime introspection
- * surface was removed in favour of static-data consumption.
- */
 import '../index'
+import './schmancy-skill'
 
 export {
 	$dialog,
@@ -27,8 +10,9 @@ export {
 	theme,
 	area,
 	lazy,
-	createContext,
-	select,
-	selectItem,
+	state,
+	bindState,
+	computed,
+	stateFromObservable,
 } from '../index'
 export { $LitElement } from '../../mixins/index'

package/src/agent/helpers.ts

@@ -0,0 +1,161 @@
+import manifest from 'virtual:schmancy-manifest'
+
+export type Manifest = typeof manifest
+
+export type ElementEntry = {
+	kind: 'class'
+	name: string
+	tagName?: string
+	description?: string
+	summary?: string
+	attributes?: Array<{
+		name: string
+		description?: string
+		type?: { text?: string }
+		default?: string
+		values?: string[]
+	}>
+	events?: Array<{ name: string; description?: string; type?: { text?: string } }>
+	slots?: Array<{ name: string; description?: string }>
+	cssProperties?: Array<{ name: string; description?: string }>
+	cssParts?: Array<{ name: string; description?: string }>
+	whenToUse?: string
+	platformPrimitive?: { tag: string; mode?: string; note?: string }
+	contexts?: { provides?: string[]; consumes?: string[] }
+}
+
+export type ServiceEntry = {
+	kind: 'variable'
+	name: string
+	description?: string
+	summary?: string
+	service: true
+	methods?: Array<{ signature: string; summary?: string }>
+}
+
+type Declaration = ElementEntry | ServiceEntry | { kind: string; name: string; [key: string]: unknown }
+
+function allDeclarations(): Declaration[] {
+	const out: Declaration[] = []
+	for (const mod of manifest.modules ?? []) {
+		const decls = (mod as unknown as { declarations?: Declaration[] }).declarations ?? []
+		for (const decl of decls) out.push(decl)
+	}
+	return out
+}
+
+function elements(): ElementEntry[] {
+	return allDeclarations().filter(
+		(d): d is ElementEntry => d.kind === 'class' && typeof (d as ElementEntry).tagName === 'string',
+	)
+}
+
+function services(): ServiceEntry[] {
+	return allDeclarations().filter((d): d is ServiceEntry => d.kind === 'variable' && (d as ServiceEntry).service === true)
+}
+
+export function help(tag?: string): unknown {
+	if (!tag) {
+		return {
+			elements: elements().map(e => ({ tag: e.tagName, summary: e.summary ?? e.description })),
+			services: services().map(s => ({ name: s.name, summary: s.summary ?? s.description })),
+		}
+	}
+	const el = elements().find(e => e.tagName === tag)
+	if (el) return el
+	const svc = services().find(s => s.name === tag)
+	if (svc) return svc
+	return null
+}
+
+export function tokens(): string[] {
+	return (manifest as { tokens?: string[] }).tokens ?? []
+}
+
+export function platformPrimitive(tag: string): ElementEntry['platformPrimitive'] | null {
+	return elements().find(e => e.tagName === tag)?.platformPrimitive ?? null
+}
+
+export function registeredTags(): string[] {
+	return elements()
+		.map(e => e.tagName!)
+		.filter(tag => typeof customElements.get(tag) !== 'undefined')
+}
+
+export function a11yAudit(): Array<{
+	tag: string
+	role: string | null
+	ariaLabel: string | null
+	hasShadowRoot: boolean
+	formAssociated: boolean
+}> {
+	const tags = new Set(elements().map(e => e.tagName!))
+	const report: Array<{
+		tag: string
+		role: string | null
+		ariaLabel: string | null
+		hasShadowRoot: boolean
+		formAssociated: boolean
+	}> = []
+	const all = document.querySelectorAll('*')
+	for (const node of Array.from(all)) {
+		const tag = node.tagName.toLowerCase()
+		if (!tags.has(tag)) continue
+		const ctor = customElements.get(tag) as (CustomElementConstructor & { formAssociated?: boolean }) | undefined
+		report.push({
+			tag,
+			role: node.getAttribute('role'),
+			ariaLabel: node.getAttribute('aria-label'),
+			hasShadowRoot: Boolean((node as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot),
+			formAssociated: Boolean(ctor?.formAssociated),
+		})
+	}
+	return report
+}
+
+export type Capabilities = {
+	popover: boolean
+	declarativeShadowDom: boolean
+	scopedRegistries: boolean
+	trustedTypes: boolean
+	cssRegisteredProperties: boolean
+	elementInternalsAria: boolean
+	formAssociated: boolean
+	adoptedStyleSheets: boolean
+}
+
+/**
+ * Runtime feature probe. Tells an agent which platform capabilities the
+ * current sandbox exposes, so it can adapt without assuming the sandbox CSP
+ * or browser version. Every check is feature-detect, not UA-sniff.
+ */
+export function capabilities(): Capabilities {
+	const anyTemplate = typeof HTMLTemplateElement !== 'undefined' ? HTMLTemplateElement.prototype : null
+	const anyElInternals = typeof ElementInternals !== 'undefined' ? ElementInternals.prototype : null
+	return {
+		popover: typeof HTMLElement !== 'undefined' && 'popover' in HTMLElement.prototype,
+		declarativeShadowDom: Boolean(anyTemplate && 'shadowRootMode' in anyTemplate),
+		scopedRegistries: (() => {
+			try {
+				// Native scoped registries require a constructible CustomElementRegistry.
+				// Pre-Safari-26/Chrome-146, the constructor throws Illegal constructor.
+				void new (window as { CustomElementRegistry?: new () => unknown }).CustomElementRegistry!()
+				return true
+			} catch {
+				return false
+			}
+		})(),
+		trustedTypes: typeof (globalThis as { trustedTypes?: unknown }).trustedTypes !== 'undefined',
+		cssRegisteredProperties: typeof (window as { CSS?: { registerProperty?: unknown } }).CSS?.registerProperty === 'function',
+		elementInternalsAria: Boolean(anyElInternals && 'role' in anyElInternals),
+		formAssociated: typeof ElementInternals !== 'undefined',
+		adoptedStyleSheets: typeof Document !== 'undefined' && 'adoptedStyleSheets' in Document.prototype,
+	}
+}
+
+export function manifestUrl(): string {
+	const blob = new Blob([JSON.stringify(manifest)], { type: 'application/json' })
+	return URL.createObjectURL(blob)
+}
+
+export { manifest }

package/src/agent/index.ts

@@ -0,0 +1 @@
+export * from './schmancy-skill'

package/src/agent/schmancy-skill.ts

@@ -0,0 +1,71 @@
+import { SchmancyElement } from '../../mixins/index'
+import { html } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import {
+	a11yAudit,
+	capabilities,
+	help,
+	manifest,
+	manifestUrl,
+	platformPrimitive,
+	registeredTags,
+	tokens,
+} from './helpers'
+
+declare global {
+	interface Window {
+		schmancy?: {
+			manifest: typeof manifest
+			manifestUrl: string
+			help: typeof help
+			tokens: typeof tokens
+			platformPrimitive: typeof platformPrimitive
+			registeredTags: typeof registeredTags
+			a11yAudit: typeof a11yAudit
+			capabilities: typeof capabilities
+		}
+	}
+}
+
+let installedUrl: string | null = null
+
+function install() {
+	if (typeof window === 'undefined') return
+	if (installedUrl) return
+	installedUrl = manifestUrl()
+	window.schmancy = {
+		manifest,
+		manifestUrl: installedUrl,
+		help,
+		tokens,
+		platformPrimitive,
+		registeredTags,
+		a11yAudit,
+		capabilities,
+	}
+}
+
+/**
+ * Self-describing runtime helper. Drop `<schmancy-skill></schmancy-skill>`
+ * once on a page and `window.schmancy.help('schmancy-button')` returns the
+ * machine-readable entry for any tag. Renders nothing.
+ *
+ * @element schmancy-skill
+ */
+@customElement('schmancy-skill')
+export class SchmancySkill extends SchmancyElement {
+	connectedCallback() {
+		super.connectedCallback()
+		install()
+	}
+
+	render() {
+		return html``
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-skill': SchmancySkill
+	}
+}

package/src/agent/virtual-manifest.d.ts

@@ -1,21 +1,10 @@
 declare module 'virtual:schmancy-manifest' {
 	type ManifestModule = { kind: 'javascript-module'; path: string; declarations: Array<Record<string, unknown>> }
-	type ManifestRule = {
-		id: string
-		scope: 'global' | 'tag' | 'token' | 'attribute' | 'workflow'
-		applies?: string[]
-		rule: string
-		severity: 'error' | 'warn' | 'hint'
-		validator?: string
-	}
 	const manifest: {
-		/** '1.1.0' adds the structured `rules` array. `conventions` stays for back-compat. */
-		schemaVersion: '1.1.0'
+		schemaVersion: '1.0.0'
 		readme?: string
 		modules: ManifestModule[]
 		tokens: string[]
-		conventions: string[]
-		rules: ManifestRule[]
 	}
 	export default manifest
 }

package/src/area/area.component.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js'
 import {
@@ -16,33 +16,21 @@ import {
 	takeUntil,
 	tap,
 } from 'rxjs'
-import area from './area.service'
+import { area } from './area.service'
 import { RouteComponent, SchmancyRoute } from './route.component'
 import { ActiveRoute, HISTORY_STRATEGY, RouteAction } from './router.types'
 
-/**
- * Router outlet — renders the active route's component for the named area. Drives the schmancy router via the `area` service.
- *
- * @element schmancy-area
- * @summary Mount once per "addressable region" of the app (typically the main content area). Use the imperative `area.push({ area, component, params })` service to navigate. Multiple named areas can coexist on a page (e.g. main content + a sheet).
- * @example
- * <schmancy-area name="main"></schmancy-area>
- * <script>
- *   import { area } from '@mhmo91/schmancy';
- *   area.push({ area: 'main', component: MyDashboardView, params: { id: 42 } });
- * </script>
- * @platform div - Routing outlet. Degrades to an empty div if the tag never registers — routing is lost but the page stays accessible.
- * @fires redirect - When the area resolves a route to a different destination (programmatic redirect). `detail.from` and `detail.to` are the route names.
- */
 @customElement('schmancy-area')
-export class SchmancyArea extends $LitElement(css`
+export class SchmancyArea extends SchmancyElement {
+	static styles = [css`
 	:host {
 		position: relative;
 		display: block;
 		inset: 0;
 		contain: layout style;
 	}
-`) {
+`]
+
 	/**
 	 * The name of the router outlet
 	 * @attr
@@ -342,7 +330,7 @@ export class SchmancyArea extends $LitElement(css`
 				if (element) {
 					if (route.params) Object.assign(element, route.params)
 					if (route.props) Object.assign(element, route.props)
-					if (route.state) (element as any).state = route.state
+					if (route.state) Object.assign(element, { state: route.state })
 				}
 
 				return { element, route }

package/src/area/area.service.test.ts

@@ -8,8 +8,6 @@ class TestAreaService {
 	public prettyURL = false
 	public enableHistoryMode = true
 
-	constructor() {}
-
 	// Copy the createCleanURL method for direct testing
 	createCleanURL(areas: Record<string, ActiveRoute>, clearQueryParams?: string[] | boolean | null): string {
 		// Get the current base path (everything except the last segment which might be encoded state)
@@ -75,9 +73,10 @@ class TestAreaService {
 		// Fallback to encoded state in URL (original behavior)
 		try {
 			// Clean up empty objects before encoding
-			const cleanedAreas: Record<string, any> = {}
+			type CleanRoute = Omit<ActiveRoute, 'area'>
+			const cleanedAreas: Record<string, CleanRoute> = {}
 			Object.entries(areas).forEach(([areaName, route]) => {
-				const cleanRoute: any = { component: route.component }
+				const cleanRoute: CleanRoute = { component: route.component }
 
 				// Only include state if it has content
 				if (route.state && Object.keys(route.state).length > 0) {
@@ -823,7 +822,7 @@ describe('AreaService - Edge Cases', () => {
 		mockLocation.pathname = '/demo/area/'
 
 		// Create a large state object
-		const largeState: Record<string, any> = {}
+		const largeState: Record<string, string> = {}
 		for (let i = 0; i < 1000; i++) {
 			largeState[`key${i}`] = `value${i}`.repeat(10)
 		}

package/src/area/area.service.ts

@@ -496,9 +496,10 @@ class AreaService implements AreaSubscription {
 		// Fallback to encoded state in URL (original behavior)
 		try {
 			// Clean up empty objects before encoding
-			const cleanedAreas: Record<string, any> = {}
+			type CleanRoute = Omit<ActiveRoute, 'area'>
+			const cleanedAreas: Record<string, CleanRoute> = {}
 			Object.entries(areas).forEach(([areaName, route]) => {
-				const cleanRoute: any = { component: route.component }
+				const cleanRoute: CleanRoute = { component: route.component }
 
 				// Only include state if it has content
 				if (route.state && Object.keys(route.state).length > 0) {
@@ -632,7 +633,7 @@ class AreaService implements AreaSubscription {
 		if (this.enableHistoryMode) {
 			try {
 				const currentState = history.state || {}
-				const schmancyAreas = { ...(currentState.schmancyAreas || {}) }
+				const schmancyAreas = { ...currentState.schmancyAreas }
 				delete schmancyAreas[name]
 
 				const newState = {

package/src/area/route.component.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index';
+import { SchmancyElement } from '@mixins/index';
 import { css, html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { Observable } from 'rxjs';
@@ -11,7 +11,7 @@ export type RouteComponent =
   | string // Tag name
   | CustomElementConstructor // Constructor function
   | HTMLElement // Existing element
-  | LazyComponent<any> 
+  | LazyComponent<CustomElementConstructor>
 
 export interface RouteConfig {
   when: string;
@@ -20,11 +20,22 @@ export interface RouteConfig {
   guard?:  ObservableGuardResult;
 }
 
+export type SchmancyRouteRedirectEvent = CustomEvent<{
+  blockedRoute: string;
+  area: string;
+  params: Record<string, string>;
+  state: Record<string, unknown>;
+  redirectTarget?: unknown;
+}>;
+
 /**
  * A marker component that holds route configuration.
  * This component doesn't render anything - it's used by schmancy-area
  * to configure routing via slot change detection.
  *
+ * @fires {SchmancyRouteRedirectEvent} redirect - Fired by the parent schmancy-area
+ *   on this element when the route's guard emits false. Listen with `@redirect`.
+ *
  * @example
  * ```html
  * <schmancy-area>
@@ -37,11 +48,13 @@ export interface RouteConfig {
  * ```
  */
 @customElement('schmancy-route')
-export class SchmancyRoute extends $LitElement(css`
+export class SchmancyRoute extends SchmancyElement {
+	static styles = [css`
   :host {
     display: none;
   }
-`) {
+`]
+
   @property({ type: String })
   when!: string;
 

package/src/area/utils.ts

@@ -45,8 +45,8 @@ export function compareCustomElementConstructors(
 		// Check if they have the same prototype chain
 		if (Object.getPrototypeOf(proto1) === Object.getPrototypeOf(proto2)) {
 			// Check if they have the same property names
-			const keys1 = Object.getOwnPropertyNames(proto1).sort()
-			const keys2 = Object.getOwnPropertyNames(proto2).sort()
+			const keys1 = Object.getOwnPropertyNames(proto1).toSorted()
+			const keys2 = Object.getOwnPropertyNames(proto2).toSorted()
 
 			return keys1.length === keys2.length && keys1.every((key, i) => key === keys2[i])
 		}
@@ -144,6 +144,7 @@ export function debounce<T extends (...args: any[]) => any>(func: T, wait: numbe
 	let timeout: ReturnType<typeof setTimeout> | null = null
 
 	return function (this: any, ...args: Parameters<T>) {
+		// oxlint-disable-next-line typescript/no-this-alias
 		const context = this
 
 		if (timeout !== null) {

package/src/audio/sound.service.ts

@@ -28,7 +28,7 @@
  */
 
 import { BehaviorSubject, distinctUntilChanged, map, shareReplay } from 'rxjs'
-import { createContext } from '../store'
+import { state } from '../state'
 import type {
 	Feeling,
 	FeelingCategory,
@@ -43,16 +43,12 @@ import type {
 // CONTEXT
 // ============================================================================
 
-/** Sound settings context - persists to local storage */
-const SoundContext = createContext<SoundThemeSettings>(
-	{
-		theme: null,
-		volume: 0.15,
-		muted: false,
-	},
-	'local',
-	'schmancy-sound-settings'
-)
+/** Sound settings — persists to localStorage under namespace `schmancy/sound`. */
+const SoundContext = state<SoundThemeSettings>('schmancy/sound').local({
+	theme: null,
+	volume: 0.15,
+	muted: false,
+})
 
 // ============================================================================
 // DEFAULT SOUND THEME