@mhmo91/schmancy 0.9.27 → 0.10.1

package/plugins/vite-plugin-schmancy-manifest.ts

@@ -0,0 +1,438 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Project, type ClassDeclaration, type SourceFile } from 'ts-morph'
+import type { Plugin } from 'vite'
+
+const VIRTUAL_ID = 'virtual:schmancy-manifest'
+const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_ID
+
+type Attribute = {
+	name: string
+	description?: string
+	type?: { text: string }
+	default?: string
+	/** Extracted enum of string-literal union members, e.g. `['filled', 'tonal', ...]`. */
+	values?: string[]
+}
+type Event = { name: string; description?: string; type?: { text: string } }
+type Slot = { name: string; description?: string }
+type CssProp = { name: string; description?: string; syntax?: string }
+type CssPart = { name: string; description?: string }
+type Context = { name: string; kind: 'provide' | 'consume' }
+
+type ElementDeclaration = {
+	kind: 'class'
+	name: string
+	tagName: string
+	description?: string
+	summary?: string
+	attributes?: Attribute[]
+	events?: Event[]
+	slots?: Slot[]
+	cssProperties?: CssProp[]
+	cssParts?: CssPart[]
+	examples?: string[]
+	whenToUse?: string
+	platformPrimitive?: { tag: string; mode?: string; note?: string }
+	contexts?: Context[]
+}
+
+type ServiceDeclaration = {
+	kind: 'variable'
+	name: string
+	description?: string
+	summary?: string
+	service: true
+	methods?: Array<{ signature: string; summary?: string }>
+}
+
+type Declaration = ElementDeclaration | ServiceDeclaration
+type Module = { kind: 'javascript-module'; path: string; declarations: Declaration[] }
+type Manifest = {
+	schemaVersion: '1.0.0'
+	readme?: string
+	modules: Module[]
+	tokens: string[]
+	conventions: string[]
+}
+
+const CONVENTIONS: string[] = [
+	'Every component extends `$LitElement`, not raw `LitElement`. Use the mixin from `@mhmo91/schmancy/mixins`.',
+	'RxJS subscriptions inside a component must end with `.pipe(takeUntil(this.disconnecting))` for automatic cleanup on disconnect.',
+	'Theme must wrap a surface: `<schmancy-theme>` provides design tokens, `<schmancy-surface>` paints the background and inherits text color.',
+	'Use `repeat()` from `lit/directives/repeat.js` for dynamic lists — never `.map()` inside `html\`\``.',
+	'Prefer `fromEvent(target, type).pipe(takeUntil(this.disconnecting))` over raw `addEventListener` inside components.',
+]
+
+function stripStars(raw: string): string {
+	return raw
+		.split('\n')
+		.map(line => line.replace(/^\s*\*\s?/, '').trim())
+		.filter(Boolean)
+		.join(' ')
+		.trim()
+}
+
+function getJsDocTags(node: { getLeadingCommentRanges(): ReturnType<ClassDeclaration['getLeadingCommentRanges']> }) {
+	const comments = node.getLeadingCommentRanges()
+	const result: { description: string; tags: Array<{ name: string; text: string }> } = {
+		description: '',
+		tags: [],
+	}
+	if (!comments.length) return result
+	const last = comments[comments.length - 1].getText()
+	if (!last.startsWith('/**')) return result
+	const body = last.slice(3, -2)
+	const lines = body.split('\n')
+	const descLines: string[] = []
+	let currentTag: { name: string; text: string } | null = null
+	for (const raw of lines) {
+		const line = raw.replace(/^\s*\*\s?/, '')
+		const tagMatch = line.match(/^@(\w+)\s*(.*)$/)
+		if (tagMatch) {
+			if (currentTag) result.tags.push(currentTag)
+			currentTag = { name: tagMatch[1], text: tagMatch[2] ?? '' }
+		} else if (currentTag) {
+			// Preserve newlines so multi-line @example bodies keep their HTML
+			// shape; single-line parsers still work because they trim/split first.
+			currentTag.text = currentTag.text ? currentTag.text + '\n' + line : line
+		} else {
+			descLines.push(line)
+		}
+	}
+	if (currentTag) result.tags.push(currentTag)
+	result.description = descLines.join(' ').trim()
+	return result
+}
+
+function flatten(text: string): string {
+	return text.replace(/\s+/g, ' ').trim()
+}
+
+function parseSlotTag(text: string): Slot {
+	const m = flatten(text).match(/^(\S+)?\s*-?\s*(.*)$/)
+	if (!m) return { name: '' }
+	const raw = m[1] ?? ''
+	const desc = (m[2] ?? '').trim()
+	const name = raw === '-' || raw === '' ? '' : raw
+	return desc ? { name, description: desc } : { name }
+}
+
+function parseFiresTag(text: string): Event {
+	const t = flatten(text)
+	const typed = t.match(/^\{([^}]+)\}\s*(\S+)\s*-?\s*(.*)$/)
+	if (typed) return { name: typed[2], type: { text: typed[1] }, ...(typed[3] ? { description: typed[3].trim() } : {}) }
+	const simple = t.match(/^(\S+)\s*-?\s*(.*)$/)
+	if (!simple) return { name: t }
+	return simple[2] ? { name: simple[1], description: simple[2].trim() } : { name: simple[1] }
+}
+
+function parseCssPropTag(text: string): CssProp {
+	const m = flatten(text).match(/^(\S+)\s*-?\s*(.*)$/)
+	if (!m) return { name: text }
+	return m[2] ? { name: m[1], description: m[2].trim() } : { name: m[1] }
+}
+
+function parseCssPartTag(text: string): CssPart {
+	return parseCssPropTag(text)
+}
+
+function cleanExampleBlock(raw: string): string {
+	// Strip Markdown fencing and drop empty leading/trailing lines.
+	const withoutFences = raw
+		.split('\n')
+		.map(line => line.replace(/^\s*```(html|ts|typescript|js|javascript)?\s*$/i, ''))
+		.join('\n')
+	return withoutFences.trim()
+}
+
+function parseAttrTag(text: string): Attribute {
+	const m = flatten(text).match(/^(\S+)\s*-?\s*(.*)$/)
+	if (!m) return { name: text }
+	return m[2] ? { name: m[1], description: m[2].trim() } : { name: m[1] }
+}
+
+function parsePlatformTag(text: string): ElementDeclaration['platformPrimitive'] {
+	const m = flatten(text).match(/^(\S+)\s*(\S+)?\s*-?\s*(.*)$/)
+	if (!m) return undefined
+	const out: { tag: string; mode?: string; note?: string } = { tag: m[1] }
+	if (m[2]) out.mode = m[2]
+	if (m[3]) out.note = m[3].trim()
+	return out
+}
+
+function extractElement(cls: ClassDeclaration): ElementDeclaration | null {
+	const decorator = cls.getDecorator('customElement')
+	if (!decorator) return null
+	const arg = decorator.getArguments()[0]
+	if (!arg) return null
+	const tagName = arg.getText().replace(/^['"`]|['"`]$/g, '')
+	if (!tagName.startsWith('schmancy-') && !tagName.startsWith('sch-')) return null
+
+	const { description, tags } = getJsDocTags(cls)
+	const attributes: Attribute[] = []
+	const events: Event[] = []
+	const slots: Slot[] = []
+	const cssProperties: CssProp[] = []
+	const cssParts: CssPart[] = []
+	const examples: string[] = []
+	const declaration: ElementDeclaration = {
+		kind: 'class',
+		name: cls.getName() ?? tagName,
+		tagName,
+	}
+	if (description) declaration.description = description
+
+	for (const tag of tags) {
+		switch (tag.name) {
+			case 'slot':
+				slots.push(parseSlotTag(tag.text))
+				break
+			case 'fires':
+			case 'event':
+				events.push(parseFiresTag(tag.text))
+				break
+			case 'cssprop':
+			case 'cssproperty':
+				cssProperties.push(parseCssPropTag(tag.text))
+				break
+			case 'csspart':
+			case 'part':
+				cssParts.push(parseCssPartTag(tag.text))
+				break
+			case 'attr':
+			case 'attribute':
+				attributes.push(parseAttrTag(tag.text))
+				break
+			case 'example': {
+				const cleaned = cleanExampleBlock(tag.text)
+				if (cleaned) examples.push(cleaned)
+				break
+			}
+			case 'summary':
+				declaration.summary = tag.text
+				break
+			case 'whenToUse':
+				declaration.whenToUse = tag.text
+				break
+			case 'platform':
+			case 'platformPrimitive': {
+				const pp = parsePlatformTag(tag.text)
+				if (pp) declaration.platformPrimitive = pp
+				break
+			}
+		}
+	}
+
+	const propertyDecls: Attribute[] = []
+	for (const prop of cls.getProperties()) {
+		const propDecorator = prop.getDecorators().find(d => d.getName() === 'property')
+		if (!propDecorator) continue
+		const attrName = readAttributeName(propDecorator, prop.getName())
+		if (attrName === false) continue
+		const attr: Attribute = { name: attrName }
+		const propType = prop.getType()
+		const typeText = propType.getText(prop)
+		if (typeText) attr.type = { text: typeText }
+		const literals = extractStringLiteralUnion(propType)
+		if (literals) attr.values = literals
+		const initializer = prop.getInitializer()
+		if (initializer) attr.default = initializer.getText()
+		const propJsDoc = getJsDocTags(prop)
+		if (propJsDoc.description) attr.description = propJsDoc.description
+		propertyDecls.push(attr)
+	}
+
+	const contexts: Context[] = []
+	for (const prop of cls.getProperties()) {
+		for (const dec of prop.getDecorators()) {
+			const name = dec.getName()
+			if (name !== 'provide' && name !== 'consume') continue
+			const arg = dec.getArguments()[0]
+			if (!arg) continue
+			const text = arg.getText()
+			const keyMatch = text.match(/context\s*:\s*([A-Za-z0-9_$.]+)/)
+			const key = keyMatch ? keyMatch[1] : text
+			contexts.push({ name: key, kind: name as 'provide' | 'consume' })
+		}
+	}
+
+	const mergedAttrs = [...propertyDecls, ...attributes.filter(a => !propertyDecls.find(p => p.name === a.name))]
+	if (mergedAttrs.length) declaration.attributes = mergedAttrs
+	if (events.length) declaration.events = events
+	if (slots.length) declaration.slots = slots
+	if (cssProperties.length) declaration.cssProperties = cssProperties
+	if (cssParts.length) declaration.cssParts = cssParts
+	if (examples.length) declaration.examples = examples
+	if (contexts.length) declaration.contexts = contexts
+
+	return declaration
+}
+
+function extractStringLiteralUnion(type: import('ts-morph').Type): string[] | undefined {
+	const nonNullable = type.getNonNullableType()
+	if (nonNullable.isStringLiteral()) {
+		const v = nonNullable.getLiteralValue()
+		return typeof v === 'string' ? [v] : undefined
+	}
+	if (!nonNullable.isUnion()) return undefined
+	const values: string[] = []
+	for (const member of nonNullable.getUnionTypes()) {
+		const m = member.getNonNullableType()
+		if (!m.isStringLiteral()) return undefined
+		const v = m.getLiteralValue()
+		if (typeof v !== 'string') return undefined
+		values.push(v)
+	}
+	return values.length ? values : undefined
+}
+
+function readAttributeName(decorator: { getArguments(): Array<{ getText(): string }> }, fallback: string): string | false {
+	const arg = decorator.getArguments()[0]
+	if (!arg) return fallback
+	const text = arg.getText()
+	if (/attribute\s*:\s*false/.test(text)) return false
+	const m = text.match(/attribute\s*:\s*['"]([^'"]+)['"]/)
+	if (m) return m[1]
+	return fallback
+}
+
+function extractServices(src: SourceFile): ServiceDeclaration[] {
+	const out: ServiceDeclaration[] = []
+	for (const decl of src.getVariableDeclarations()) {
+		if (!decl.isExported()) continue
+		const name = decl.getName()
+		const statement = decl.getVariableStatement()
+		if (!statement) continue
+		const { description, tags } = getJsDocTags(statement)
+		const hasServiceTag = tags.some(t => t.name === 'service')
+		if (!hasServiceTag) continue
+		const service: ServiceDeclaration = { kind: 'variable', name, service: true }
+		if (description) service.description = description
+		const methods: Array<{ signature: string; summary?: string }> = []
+		for (const tag of tags) {
+			if (tag.name === 'summary') service.summary = flatten(tag.text)
+			else if (tag.name === 'method') {
+				const flat = flatten(tag.text)
+				const m = flat.match(/^(\S+\([^)]*\)(?:\s*:\s*\S+)?)\s*-?\s*(.*)$/)
+				if (m) methods.push(m[2] ? { signature: m[1], summary: m[2].trim() } : { signature: m[1] })
+				else methods.push({ signature: flat })
+			}
+		}
+		if (methods.length) service.methods = methods
+		out.push(service)
+	}
+	return out
+}
+
+function extractTokens(srcDir: string): string[] {
+	const tokens = new Set<string>()
+	const iface = readIfExists(resolve(srcDir, 'theme/theme.interface.ts'))
+	if (iface) {
+		for (const m of iface.matchAll(/var\(--(schmancy-sys-[a-zA-Z0-9-]+)\)/g)) {
+			tokens.add(m[1])
+		}
+	}
+	const css = readIfExists(resolve(srcDir, 'theme/theme.style.css'))
+	if (css) {
+		for (const m of css.matchAll(/--(schmancy-[a-zA-Z0-9-]+)\s*:/g)) {
+			tokens.add(m[1])
+		}
+	}
+	return Array.from(tokens).sort()
+}
+
+function readIfExists(path: string): string | null {
+	try {
+		return readFileSync(path, 'utf8')
+	} catch {
+		return null
+	}
+}
+
+function buildManifest(project: Project, srcDir: string, readme: string | null): Manifest {
+	const modules: Module[] = []
+	const sources = project
+		.getSourceFiles()
+		.filter(f => f.getFilePath().startsWith(srcDir) && !f.getFilePath().endsWith('.d.ts'))
+
+	for (const src of sources) {
+		const declarations: Declaration[] = []
+		for (const cls of src.getClasses()) {
+			const element = extractElement(cls)
+			if (element) declarations.push(element)
+		}
+		for (const svc of extractServices(src)) declarations.push(svc)
+		if (declarations.length) {
+			modules.push({
+				kind: 'javascript-module',
+				path: src.getFilePath().slice(srcDir.length + 1),
+				declarations,
+			})
+		}
+	}
+
+	return {
+		schemaVersion: '1.0.0',
+		...(readme ? { readme } : {}),
+		modules,
+		tokens: extractTokens(srcDir),
+		conventions: CONVENTIONS,
+	}
+}
+
+export interface SchmancyManifestPluginOptions {
+	/** Absolute path to packages/schmancy (defaults to plugin invocation cwd). */
+	root?: string
+}
+
+export default function schmancyManifestPlugin(options: SchmancyManifestPluginOptions = {}): Plugin {
+	const root = options.root ?? process.cwd()
+	const srcDir = resolve(root, 'src')
+	const tsConfigFilePath = resolve(root, 'tsconfig.json')
+	let project: Project | null = null
+	let cachedManifest: Manifest | null = null
+
+	function ensureProject(): Project {
+		if (!project) {
+			project = new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: false })
+		}
+		return project
+	}
+
+	function compute(): Manifest {
+		const p = ensureProject()
+		const readme = readIfExists(resolve(root, 'README.md'))
+		cachedManifest = buildManifest(p, srcDir, readme)
+		return cachedManifest
+	}
+
+	return {
+		name: 'schmancy-manifest',
+		enforce: 'post',
+
+		buildStart() {
+			compute()
+		},
+
+		resolveId(id) {
+			if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID
+			return null
+		},
+
+		load(id) {
+			if (id !== RESOLVED_VIRTUAL_ID) return null
+			const manifest = cachedManifest ?? compute()
+			return `export default ${JSON.stringify(manifest)};`
+		},
+
+		generateBundle() {
+			const manifest = cachedManifest ?? compute()
+			this.emitFile({
+				type: 'asset',
+				fileName: 'schmancy.manifest.json',
+				source: JSON.stringify(manifest, null, 2),
+			})
+		},
+	}
+}

package/skills/schmancy/INDEX.md

@@ -7,7 +7,7 @@ A Web Component UI library on Lit + RxJS + Tailwind CSS.
 The framework pieces — touch before components.
 
 - [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
-- [Store](./store.md) — `createContext`, `@select`, `@selectItem`, storage backends.
+- [State](./state.md) — `state()` factory (memory / session / local / idb), variant write APIs (`Object` / `Map` / `Set` / `Array` / `Scalar`), `bindState`, `computed`, `stateFromObservable`.
 - [Mixins](./mixins.md) — `$LitElement` base class.
 - [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
 - [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.

package/skills/schmancy/SKILL.md

@@ -21,8 +21,8 @@ All reference files live in this directory. Read by filename.
 | Piece | Read |
 |-------|------|
 | Routing (`<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()`) | `area.md` |
-| State (`createContext`, `@select`, `@selectItem`) | `store.md` |
-| Base class (`$LitElement`) | `mixins.md` |
+| State (`state()`, `bindState`, `computed`, `stateFromObservable`) | `state.md` |
+| Base class (`SchmancyElement`) | `mixins.md` |
 | Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
 | Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
 | Spring physics presets | `animation.md` |
@@ -45,10 +45,19 @@ References: `dialog.md`, `notification.md`, `content-drawer.md`, `sheet.md`.
 
 Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip>`, `<schmancy-lightbox>`, `<schmancy-expand>`) only when the tag is the natural fit (anchored panels, tooltips, galleries).
 
+## Composition
+
+- **Audit by grep** (`AUDIT_BY_GREP`). An agent's compliance report on a file under a rule is the list of file:line citations of the rule's forbidden patterns; an empty list is compliance. The rule applies to every other rule in this skill (`PRIMITIVE_FIRST`, `TOKEN_FIRST_NO_ARBITRARY`, `NO_LOCAL_CLASS_CSS`, `NO_TERNARY_NOTHING_DISPATCH`): a claim that a file complies is a claim about what the file does NOT contain, and that claim is verified by enumerating the rule's forbidden patterns and grepping each one.
+  Sources: each rule above names its forbidden patterns explicitly — `TOKEN_FIRST_NO_ARBITRARY` forbids `[...]` arbitrary-value Tailwind utilities; `PRIMITIVE_FIRST` forbids raw HTML elements whose class attribute carries design-system styling (typography/color/surface/spacing-as-design); `NO_LOCAL_CLASS_CSS` forbids class/id/attribute selectors inside the `css` template; `NO_TERNARY_NOTHING_DISPATCH` forbids `${cond ? html\`...\` : nothing}` and `${cond && html\`...\`}` patterns.
+  Remediation: before reporting any file compliant, run a grep against each forbidden pattern named by the rule under audit (e.g. `grep -nE '\[(?:[^]]+)\]' <file>` for `TOKEN_FIRST_NO_ARBITRARY`; `grep -nE 'class="[^"]*\b(text-|bg-|border-|rounded-|shadow-|tracking-|leading-|p[xy]?-)' <file>` plus a manual scan for raw `<div>`/`<span>` carrying those classes for `PRIMITIVE_FIRST`). The compliance report's body is the concatenation of those grep outputs annotated with their rule name; an empty body across every pattern under every rule is the only form of "compliant". A claim of compliance unaccompanied by the grep evidence is not a compliance report and is treated as an unverified assertion that the audit loop rejects.
+- **Schmancy primitive first** (`PRIMITIVE_FIRST`). Within `web/**`, every visible UI element is a custom element exported from `packages/schmancy/src/**`, and an element absent from that export set is added there before being imported into `web/**`. The rule sits above the styling rules: a `<div class="text-xs text-surface-on-variant">…</div>` whose role is typography is a violation even when every utility resolves to a registered token, because `<schmancy-typography>` already covers that role; the styling rules apply only to whatever class strings remain after the right primitive has been selected.
+  Sources: [packages/schmancy/skills/schmancy/INDEX.md](../INDEX.md) catalogues the export set by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display); each role's reference file (`typography.md`, `surface.md`, `button.md`, `dialog.md`, `sheet.md`, …) names the props, slots, and events that displace the equivalent `<div>` + utility-class pattern. The export set is the single source — a primitive that is not exported from `packages/schmancy/src/**` does not satisfy this rule even if it lives in a private file inside the schmancy tree.
+  Remediation: walk every `.ts` and `.html` file under `web/**` and list every raw HTML element whose class string carries design-system styling (typography, color, spacing-as-design-decision, surface, layout-as-design-decision, motion, overlay) — those are the violations. For each, look up the matching schmancy primitive in `INDEX.md` and rewrite the element through that primitive (`<schmancy-typography type=… token=…>` for type-scale text, `<schmancy-surface type=… fill=…>` for elevated/bounded surfaces, `<schmancy-grid>`/`<schmancy-flex>` for layout primitives with design intent, the imperative `$dialog`/`$notify`/`sheet.open`/`schmancyContentDrawer.open` services for overlays, `<schmancy-scroll>` for scroll containers). When a needed primitive is absent from the export set, design and implement it as a new component under `packages/schmancy/src/<role>/` — extending `$LitElement(style?)`, registered in `HTMLElementTagNameMap`, exported through the package barrel, and documented with a sibling `.md` in the skill's reference set — and only then introduce the first call site in `web/**`. The audit subagent iterates the whole `web/**` tree, surfaces the violation list, applies the rewrites, runs `yarn workspace @momo/web tsc --noEmit` plus the colocated `*-view.test.ts` suites, and reports pre-existing violations that require a new schmancy primitive as a separate punch list for designer/architect approval before the implementation lands. The loop exits when every `web/**` file's visible UI elements are schmancy primitives and the typecheck plus the test suites pass.
+
 ## Non-negotiable conventions
 
 **Component authoring**
-- Every component extends `$LitElement(style?)`. Never raw `LitElement`.
+- Every component extends `SchmancyElement` and declares its component-local CSS via `static styles = [css\`...\`]`. Never raw `LitElement`. Never wrap with `SignalWatcher` — the base already includes it; double-wrapping creates two nested Computeds and panics with "Detected cycle in computations" at runtime. The deprecated `$LitElement(style?)` factory still works (it now just delegates to SchmancyElement) but should not appear in new code.
 - Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`.
 - Register the tag in `HTMLElementTagNameMap` for TypeScript.
 
@@ -72,9 +81,12 @@ Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip
 - `classMap(this.classMap({...}))` must be the sole expression in `class=` — never mix with string interpolation.
 
 **Styling**
-- Styling uses Tailwind and schmancy tokens. The `css` template passed to `$LitElement` contains only `:host` rules, `@keyframes`, and selectors targeting vendor pseudo-elements (`::-webkit-*`, `::-moz-*`). Other styling is set through Tailwind utility classes and schmancy theme tokens on the `class=` attribute. The `style=` attribute holds per-instance dynamic values only (e.g. `style="--tide: ${value}"`).
+- Styling uses Tailwind and schmancy tokens. The `css` block in `static styles` contains only `:host` rules, `@keyframes`, and selectors targeting vendor pseudo-elements (`::-webkit-*`, `::-moz-*`). Other styling is set through Tailwind utility classes and schmancy theme tokens on the `class=` attribute. The `style=` attribute holds per-instance dynamic values only (e.g. `style="--tide: ${value}"`).
   Remediation: move declarations to Tailwind on the `class=` attribute (`backdrop-filter: blur(20px)` → `backdrop-blur-xl`; `color-mix(in oklch, Canvas 72%, transparent)` → `bg-surface/70`; `border-radius: 14px` → `rounded-2xl`; `transition: opacity 80ms linear` → `transition-opacity duration-75 ease-linear`). When a visual pattern seems to want its own class (like `.glass`), check `INDEX.md` — schmancy likely ships the component.
-- Colors: **Tailwind theme classes** (`bg-primary-default`, `text-surface-on`, `border-outline-variant`, …) — every `--schmancy-sys-color-*` token is exposed as a Tailwind color utility, so prefer the Tailwind class. Fall back to the `--schmancy-sys-color-*` CSS var only when Tailwind lacks a utility for the specific property. Never hardcoded hex, never arbitrary values like `bg-[#ff0000]`.
+- Colors: Tailwind utility classes (`bg-surface-on`, `text-primary-default`, `border-outline-variant`) are the preferred surface — every `--schmancy-sys-color-*` token is auto-aliased to `--color-*`, which Tailwind v4 turns into the full `bg-X` / `text-X` / `border-X` / `ring-X` / `fill-X` / `stroke-X` namespace. Reach for raw `var(--schmancy-sys-color-*)` only inside the `css` template literal (where Tailwind doesn't apply) or for custom tokens you've registered yourself. Never hardcoded hex.
+- **No arbitrary-value escape** (`TOKEN_FIRST_NO_ARBITRARY`). Within `web/src/**` and `packages/schmancy/src/**`, no Tailwind arbitrary-value utility (`[...]`) appears; a value not yet covered by `packages/schmancy/src/theme/theme.style.css` or the Tailwind default theme is added as a token to that file before being used. This rule supersedes the prior `TOKEN_FIRST_LITERALS_COMPLETION` annotation form: an inline `// token-gap: <namespace>` comment is no longer a valid resolution, since color and size namespaces are exhaustively covered by schmancy and Tailwind, and any uncovered namespace (aspect ratio, motion curve, custom breakpoint) is itself a token-registry extension waiting to be made.
+  Sources: `theme.md` enumerates the schmancy color tokens (every `--schmancy-sys-color-*` auto-aliases to a Tailwind class); `typography.md` enumerates the type scale; `theme.style.css` declares the spacing, radius, shadow, font, text, tracking, leading, aspect, breakpoint, container, ease, and animate namespaces, every entry of which Tailwind v4 lifts into a named utility. A bracket-syntax utility in either glob is by construction either a value the registry already covers (rule violation, replace with the token) or a value the registry does not yet cover (rule violation, extend the registry first).
+  Remediation: list every `[...]` arbitrary-value utility in the changeset; for each whose value matches a `--<namespace>-*` variable, replace with the named utility (`bg-[#faf7f2]` → `bg-surface-containerLowest`, `max-w-[720px]` → `max-w-3xl`); for each whose value has no matching variable, register the variable in `packages/schmancy/src/theme/theme.style.css` first, then mirror the same `--<namespace>-x: …` declaration inside an `@theme {}` block in the consumer's stylesheet (e.g. `web/src/styles.css`) — schmancy ships the variable to its own shadow-DOM TailwindMixin, the consumer mirror lets Tailwind v4 generate the named utility for document-scope code. When the variable lives in both places but the utility class still does not apply inside a shadow-DOM component (the mixin's utility subset is frozen at schmancy build time, so consumer-introduced class names can't be added), bind the registered variable through an inline `style="<property>: var(--<namespace>-x);"` attribute on the element — the bracket-syntax rule is satisfied because no Tailwind arbitrary-value utility appears in the markup, and the `style=` attribute consuming a registered CSS custom property fits the per-instance dynamic-value clause of `NO_LOCAL_CLASS_CSS`. When the value's design rationale is one-off (a vendor-dictated pixel width, a single-use marketing graphic) the rule still requires a registered token — the alternative is to drop the value as a design violation.
 - No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
 
 **Accessibility (combobox forms)**

package/skills/schmancy/mixins.md

@@ -1,37 +1,70 @@
-# `$LitElement`
+# `SchmancyElement`
 
-Base class for Schmancy components. Extends `LitElement` with RxJS cleanup, Tailwind support, and cross-shadow discovery.
+Base class for Schmancy components. A concrete named class — not a mixin
+factory — composing `LitElement` + Tailwind injection + `BaseElement`
+(the `disconnecting` Subject, `classMap`, `styleMap`, discovery, `stableId`,
+`uid`, `locale`) + `SignalWatcher` (auto-tracks every signal read in `render()`).
 
 ## Usage
 
 ```typescript
-import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { SchmancyElement } from '@mhmo91/schmancy/mixins'
 import { customElement } from 'lit/decorators.js'
 import { css, html } from 'lit'
 
 @customElement('my-component')
-class MyComponent extends $LitElement(css`
-  :host { display: block; }
-`) {
+class MyComponent extends SchmancyElement {
+  static styles = [css`
+    :host { display: block }
+  `]
+
   render() {
     return html`<slot></slot>`
   }
 }
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': MyComponent
+  }
+}
+```
+
+No styles? Just drop `static styles`:
+
+```typescript
+@customElement('my-component')
+class MyComponent extends SchmancyElement {
+  render() { return html`<slot></slot>` }
+}
 ```
 
-`$LitElement(style?)` accepts either a Lit `css` tagged literal or a string (e.g. SCSS imported with `?inline`).
+Tailwind is injected automatically — your `static styles` only declares
+component-local CSS.
 
 ## Provided members
 
-### `disconnecting: Subject<void>`
+### `disconnecting: Subject<void>` (RxJS)
 Emits once when the element disconnects. Pair with `takeUntil` for cleanup:
 
 ```typescript
 connectedCallback() {
   super.connectedCallback()
-  someObservable$.pipe(
-    takeUntil(this.disconnecting),
-  ).subscribe()
+  someObservable$
+    .pipe(takeUntil(this.disconnecting))
+    .subscribe()
+}
+```
+
+### `disconnectedSignal: AbortSignal` (native)
+Aborts when the element disconnects. Use with any AbortSignal-aware API —
+no RxJS conversion needed:
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+  fetch('/api/stream', { signal: this.disconnectedSignal })
+  someElement.addEventListener('click', handler, { signal: this.disconnectedSignal })
 }
 ```
 
@@ -50,27 +83,26 @@ Must be the only expression in `class=` — don't mix with string interpolation.
 ### `styleMap(obj)`
 Passthrough to Lit's `styleMap`.
 
-```typescript
-html`<div style=${this.styleMap({ width: `${w}px` })}></div>`
-```
-
 ### `discover<T>(tag): Observable<T | null>`
 Find another Schmancy component by tag via event-based handshake. Works across shadow DOM.
 
 ```typescript
-this.discover<SchmancyDialog>('schmancy-dialog').pipe(
-  takeUntil(this.disconnecting),
-).subscribe(dialog => dialog?.setDefaultAction('confirm'))
+this.discover<SchmancyDialog>('schmancy-dialog')
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(dialog => dialog?.setDefaultAction('confirm'))
 ```
 
 ### Auto-response to discovery
-Every `$LitElement` responds to `{its-tag}-where-are-you` events with `{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
+Every SchmancyElement responds to `{its-tag}-where-are-you` events with
+`{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
 
 ## Component skeleton
 
 ```typescript
 @customElement('my-component')
-export class MyComponent extends $LitElement(css`:host { display: block }`) {
+export class MyComponent extends SchmancyElement {
+  static styles = [css`:host { display: block }`]
+
   @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
   @state() private _open = false
 
@@ -95,5 +127,31 @@ declare global {
 
 - Call `super.connectedCallback()` / `super.disconnectedCallback()` when overriding.
 - All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- All AbortSignal-aware API calls pass `{ signal: this.disconnectedSignal }`.
 - Register the tag in `HTMLElementTagNameMap` for TypeScript.
 - Don't mix `classMap` with string interpolation in the same attribute.
+- **Never wrap with `SignalWatcher`** — it is already part of SchmancyElement.
+  `SignalWatcher(SchmancyElement)` creates two nested Computeds and panics
+  with "Detected cycle in computations" at runtime. The pre-edit lint rule
+  (`NO_SIGNAL_WATCHER_WRAP`) blocks it.
+
+## Migration: `$LitElement` (deprecated)
+
+`$LitElement(style?)` is a thin alias kept for the migration window. It
+returns a class that extends SchmancyElement with the passed style as
+`static styles`. Existing code keeps compiling and running unchanged. New
+code uses SchmancyElement directly:
+
+```typescript
+// Before
+class MyView extends $LitElement(css`:host { display: block }`) { … }
+
+// After
+class MyView extends SchmancyElement {
+  static styles = [css`:host { display: block }`]
+  …
+}
+```
+
+The `$LitElement` factory will be removed in the next major Schmancy
+release. The pre-edit lint rule (`PREFER_SCHMANCY_ELEMENT`) flags new uses.