@prongsjs/ui 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Poling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @prongsjs/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.
+The Prongs UI profile: intents that resolve to an element, ARIA attributes and Tailwind classes, the theme (`@prongsjs/ui/theme`, with self-layering surfaces), and the checks that find raw styling and overrides.
+
+`npx prongs add` copies the components (`Text`, `Action`, `Field`, `Layout`, `Media`, `Dialog`, `Popover`) and a starter registry into your repo, so you own them. Peer dependency: `tailwind-merge`. Early (0.x): expect changes. Full guide: https://github.com/drewpoling2/prongs#readme

package/dist/classes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Classifies Tailwind classes as layout (where an element sits) or visual
+ * (what it looks like). Intents own visual identity; layout is the only thing
+ * a call site may add, and only on Layout.
+ */
+/** Removes variants (`md:`, `hover:`, `[&>*]:`) and the important modifier. */
+export declare function stripVariants(cls: string): string;
+export declare function isLayoutClass(cls: string): boolean;
+/** True for classes that set text size, colour, weight or style. */
+export declare function isTextStyleClass(cls: string): boolean;
+/** True for any class that changes how something looks rather than where it sits. */
+export declare function isVisualClass(cls: string): boolean;
+export declare function splitClasses(value: string | undefined | null): string[];
+/**
+ * What a className does to an intent's classes: which visual classes it adds,
+ * and which of the intent's classes it overrides.
+ */
+export declare function analyzeClassName(intentClasses: string | undefined, className: string | undefined, merge: (...c: (string | undefined)[]) => string): {
+    visual: string[];
+    overridden: string[];
+};
+/** Jaccard similarity of two class lists, ignoring variants. */
+export declare function classSimilarity(a: readonly string[], b: readonly string[]): number;

package/dist/classes.js

@@ -0,0 +1,98 @@
+/**
+ * Classifies Tailwind classes as layout (where an element sits) or visual
+ * (what it looks like). Intents own visual identity; layout is the only thing
+ * a call site may add, and only on Layout.
+ */
+/** Removes variants (`md:`, `hover:`, `[&>*]:`) and the important modifier. */
+export function stripVariants(cls) {
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < cls.length; i++) {
+        const ch = cls[i];
+        if (ch === '[' || ch === '(')
+            depth++;
+        else if (ch === ']' || ch === ')')
+            depth--;
+        else if (ch === ':' && depth === 0)
+            start = i + 1;
+    }
+    return cls.slice(start).replace(/^!/, '').replace(/!$/, '');
+}
+const LAYOUT_PATTERNS = [
+    // box size and position
+    /^-?m[trblxyse]?-/,
+    /^(min-|max-)?[wh]-/,
+    /^size-/,
+    /^(static|fixed|absolute|relative|sticky)$/,
+    /^-?(inset|top|right|bottom|left|start|end)(-[xy])?-/,
+    /^z-/,
+    /^(hidden|block|inline|inline-block|contents|flow-root|sr-only|not-sr-only)$/,
+    /^(overflow|overscroll)(-[xy])?-/,
+    /^-?scroll-[mp][trblxyse]?-/,
+    /^aspect-/,
+    /^object-/,
+    // flex and grid
+    /^(flex|inline-flex|grid|inline-grid)$/,
+    // flex-1, flex-3, flex-[2_1_0%]: how a box shares the row, which is layout.
+    /^flex-(row|col|wrap|nowrap|auto|initial|none|\d+|\[[^\]]+\])/,
+    /^(flex-)?(grow|shrink)(-\d+|-\[[^\]]+\])?$/,
+    /^basis-/,
+    /^order-/,
+    /^(items|justify|content|self|place)-/,
+    /^(col|row)-/,
+    /^grid-(cols|rows|flow)-/,
+    /^auto-(cols|rows)-/,
+    // spacing between and inside
+    /^gap(-[xy])?-/,
+    /^-?space-[xy]-/,
+    /^p[trblxyse]?-/,
+    // text flow (not text style)
+    /^text-(left|center|right|justify|start|end|balance|pretty|wrap|nowrap)$/,
+    /^(truncate|text-ellipsis|text-clip)$/,
+    /^line-clamp-/,
+    /^whitespace-/,
+    /^break-/,
+];
+export function isLayoutClass(cls) {
+    const base = stripVariants(cls);
+    return LAYOUT_PATTERNS.some((pattern) => pattern.test(base));
+}
+const TEXT_STYLE = /^(font-|leading-|tracking-|(uppercase|lowercase|capitalize|normal-case|italic|not-italic|underline|line-through|tabular-nums)$)/;
+/** True for classes that set text size, colour, weight or style. */
+export function isTextStyleClass(cls) {
+    const base = stripVariants(cls);
+    if (TEXT_STYLE.test(base))
+        return true;
+    return base.startsWith('text-') && !isLayoutClass(base);
+}
+/** True for any class that changes how something looks rather than where it sits. */
+export function isVisualClass(cls) {
+    return !isLayoutClass(cls);
+}
+export function splitClasses(value) {
+    return (value ?? '').split(/\s+/).filter(Boolean);
+}
+/**
+ * What a className does to an intent's classes: which visual classes it adds,
+ * and which of the intent's classes it overrides.
+ */
+export function analyzeClassName(intentClasses, className, merge) {
+    const own = splitClasses(intentClasses);
+    const merged = new Set(splitClasses(merge(intentClasses, className)));
+    return {
+        visual: splitClasses(className).filter(isVisualClass),
+        overridden: own.filter((cls) => !merged.has(cls)),
+    };
+}
+/** Jaccard similarity of two class lists, ignoring variants. */
+export function classSimilarity(a, b) {
+    const left = new Set(a.map(stripVariants));
+    const right = new Set(b.map(stripVariants));
+    if (left.size === 0 && right.size === 0)
+        return 0;
+    let shared = 0;
+    for (const cls of left)
+        if (right.has(cls))
+            shared++;
+    return shared / (left.size + right.size - shared);
+}

package/dist/dev.d.ts

@@ -0,0 +1,14 @@
+export declare function isDev(): boolean;
+/**
+ * When elements carry `data-intent`: `always` (the default) so analytics, tests and A/B tools can
+ * find elements by purpose in production; `development` to keep intent names out of production
+ * HTML; `never` to leave it off.
+ */
+export type IntentAttribute = 'always' | 'development' | 'never';
+/** The value for `data-intent` under the project's setting, or undefined to leave it off. */
+export declare function intentAttr(intent: string, mode?: IntentAttribute): string | undefined;
+/** The intent id in development, undefined in production. Kept for components written before `intentAttr`. */
+export declare function devIntent(intent: string): string | undefined;
+export declare function warnOnce(key: string, message: string): void;
+/** Warns (once, in development) when a Layout's className carries visual classes. */
+export declare function checkLayoutClassName(intent: string, className: string | undefined): void;

package/dist/dev.js

@@ -0,0 +1,36 @@
+import { isVisualClass, splitClasses } from './classes.js';
+export function isDev() {
+    try {
+        return process.env.NODE_ENV !== 'production';
+    }
+    catch {
+        return false;
+    }
+}
+/** The value for `data-intent` under the project's setting, or undefined to leave it off. */
+export function intentAttr(intent, mode = 'always') {
+    if (mode === 'always')
+        return intent;
+    return mode === 'development' && isDev() ? intent : undefined;
+}
+/** The intent id in development, undefined in production. Kept for components written before `intentAttr`. */
+export function devIntent(intent) {
+    return intentAttr(intent, 'development');
+}
+const warned = new Set();
+export function warnOnce(key, message) {
+    if (!isDev() || warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(`[prongs] ${message}`);
+}
+/** Warns (once, in development) when a Layout's className carries visual classes. */
+export function checkLayoutClassName(intent, className) {
+    if (!className || !isDev())
+        return;
+    const visual = splitClasses(className).filter(isVisualClass);
+    if (visual.length === 0)
+        return;
+    warnOnce(`${intent}|${className}`, `${intent}: className "${className}" has visual classes (${visual.join(' ')}). ` +
+        'Layout className is for layout and spacing only. Add or change an intent, or use unsafeClassName with a reason.');
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createUiProfile, uiProfile } from './profile.js';
+export type { ClassMerge, UiBinding, UiProfile, UiProfileOptions } from './profile.js';
+export { ALLOWED_ELEMENTS, COMPONENT_DOMAINS, COMPONENT_NAMES, LOOK_DOMAINS, LOOK_WORDS, MEANING_DOMAINS, componentFor, isLookDomain, } from './vocabulary.js';
+export type { ComponentName, LookDomain, MeaningDomain } from './vocabulary.js';
+export { analyzeClassName, classSimilarity, isLayoutClass, isTextStyleClass, isVisualClass, splitClasses, stripVariants, } from './classes.js';
+export { checkLayoutClassName, devIntent, intentAttr, isDev, warnOnce, type IntentAttribute } from './dev.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createUiProfile, uiProfile } from './profile.js';
+export { ALLOWED_ELEMENTS, COMPONENT_DOMAINS, COMPONENT_NAMES, LOOK_DOMAINS, LOOK_WORDS, MEANING_DOMAINS, componentFor, isLookDomain, } from './vocabulary.js';
+export { analyzeClassName, classSimilarity, isLayoutClass, isTextStyleClass, isVisualClass, splitClasses, stripVariants, } from './classes.js';
+export { checkLayoutClassName, devIntent, intentAttr, isDev, warnOnce } from './dev.js';

package/dist/profile.d.ts

@@ -0,0 +1,26 @@
+import { type Profile } from '@prongsjs/core';
+export type UiBinding = {
+    /** Tailwind classes. Keep them in your own source so Tailwind can see them. */
+    classes?: string;
+    /** Element the component renders, e.g. 'h1' or 'textarea'. */
+    element?: string;
+    ariaRole?: string;
+    /** Extra attributes the element needs to behave correctly, e.g. { type: 'email' }. */
+    behavior?: Readonly<Record<string, string | boolean>>;
+};
+export type ClassMerge = (...classes: (string | false | null | undefined)[]) => string;
+export type UiProfile = Profile<UiBinding> & {
+    /** The class merger this profile uses. Components use it too, so conflicts resolve the same way. */
+    classes: ClassMerge;
+};
+export type UiProfileOptions = {
+    /** A tailwind-merge instance configured for your theme (extendTailwindMerge). Defaults to twMerge. */
+    merge?: ClassMerge;
+    /**
+     * Words meaning intents may not use in their ids, because they name a look or a widget.
+     * Defaults to LOOK_WORDS. Pass a function to adjust the list: (words) => words.filter(...).
+     */
+    lookWords?: readonly string[] | ((defaults: readonly string[]) => readonly string[]);
+};
+export declare function createUiProfile(options?: UiProfileOptions): UiProfile;
+export declare const uiProfile: UiProfile;

package/dist/profile.js

@@ -0,0 +1,101 @@
+import { twMerge } from 'tailwind-merge';
+import { domainOf } from '@prongsjs/core';
+import { ALLOWED_ELEMENTS, LOOK_DOMAINS, LOOK_WORDS, MEANING_DOMAINS, componentFor, isLookDomain, } from './vocabulary.js';
+export function createUiProfile(options = {}) {
+    const classes = options.merge ?? twMerge;
+    const lookWords = new Set(typeof options.lookWords === 'function' ? options.lookWords(LOOK_WORDS) : options.lookWords ?? LOOK_WORDS);
+    return {
+        name: 'ui',
+        domains: [...MEANING_DOMAINS, ...LOOK_DOMAINS],
+        internalDomains: LOOK_DOMAINS,
+        classes,
+        merge(base, next) {
+            if (!base)
+                return { ...next };
+            if (!next)
+                return base;
+            return {
+                classes: classes(base.classes, next.classes) || undefined,
+                element: next.element ?? base.element,
+                ariaRole: next.ariaRole ?? base.ariaRole,
+                behavior: base.behavior || next.behavior ? { ...base.behavior, ...next.behavior } : undefined,
+            };
+        },
+        validate(id, intent) {
+            const problems = [];
+            const domain = domainOf(id);
+            const binding = intent.binding;
+            for (const ref of intent.refs ?? []) {
+                const refDomain = domainOf(ref);
+                if (isLookDomain(domain) && !isLookDomain(refDomain)) {
+                    problems.push(`look intents may only ref other look intents, not "${ref}"`);
+                }
+                if (!isLookDomain(domain) && !isLookDomain(refDomain) && refDomain !== domain) {
+                    problems.push(`may ref look intents or intents in its own domain, not "${ref}"`);
+                }
+            }
+            if (isLookDomain(domain)) {
+                if (binding?.element || binding?.ariaRole || binding?.behavior) {
+                    problems.push('look intents only carry classes; element, ariaRole and behavior belong on meaning intents');
+                }
+                return problems;
+            }
+            for (const word of id.split('.').slice(1)) {
+                if (lookWords.has(word)) {
+                    problems.push(`"${word}" describes a look or a widget, not a purpose. Name the intent for what the element is for or does (e.g. action.share, layout.group, nav.view); put looks in the look layer.`);
+                }
+            }
+            const component = componentFor(id);
+            if (binding?.element && component && !ALLOWED_ELEMENTS[component].includes(binding.element)) {
+                problems.push(ALLOWED_ELEMENTS[component].length
+                    ? `element "${binding.element}" is not allowed for ${component} (allowed: ${ALLOWED_ELEMENTS[component].join(', ')})`
+                    : `${component} decides its own element; remove "element"`);
+            }
+            if (binding?.behavior && domain === 'popover') {
+                const keys = Object.keys(binding.behavior);
+                if (keys.some((key) => key !== 'selection') || !['one', 'many'].includes(String(binding.behavior.selection))) {
+                    problems.push("a popover's behavior is only { selection: 'one' | 'many' }: how many of its options can be picked");
+                }
+            }
+            else if (binding?.behavior && !['action', 'nav', 'choice', 'field'].includes(domain)) {
+                problems.push('behavior is only for action, nav, choice and field intents, and selection on popover intents');
+            }
+            return problems;
+        },
+        validateAll(defs) {
+            // Neighbours must contrast: in a domain with more than two intents, each one needs a
+            // "not for ... use instead" link to or from a sibling, or an agent cannot tell them apart.
+            const issues = [];
+            const byDomain = new Map();
+            for (const id of Object.keys(defs)) {
+                const domain = domainOf(id);
+                // Variants (domain.meaning.variant) are told apart by their parent's name.
+                if (isLookDomain(domain) || id.split('.').length > 2)
+                    continue;
+                byDomain.set(domain, [...(byDomain.get(domain) ?? []), id]);
+            }
+            for (const ids of byDomain.values()) {
+                if (ids.length <= 2)
+                    continue;
+                const linked = new Set();
+                for (const id of ids) {
+                    for (const e of defs[id].notFor ?? []) {
+                        if (e.instead && ids.includes(e.instead)) {
+                            linked.add(id);
+                            linked.add(e.instead);
+                        }
+                    }
+                }
+                for (const id of ids.filter((i) => !linked.has(i))) {
+                    issues.push({
+                        id,
+                        severity: 'warning',
+                        message: `no "not for ... use instead" link to or from another ${domainOf(id)}.* intent; agents will struggle to tell it apart from its neighbours`,
+                    });
+                }
+            }
+            return issues;
+        },
+    };
+}
+export const uiProfile = createUiProfile();

package/dist/tooling/analyze.d.ts

@@ -0,0 +1,42 @@
+import type { SourceFile } from '@prongsjs/core/engine';
+import { type ComponentName } from '../vocabulary.js';
+/** A JSX attribute's value, reduced to what static analysis can know. */
+export type StaticValue = {
+    kind: 'absent';
+} | {
+    kind: 'strings';
+    values: string[];
+} | {
+    kind: 'dynamic';
+};
+export type JsxSite = {
+    tag: string;
+    /** Set when the tag is a Prongs component imported from the components dir. */
+    component?: ComponentName;
+    /** True when the tag is next/link's Link. */
+    nextLink: boolean;
+    offset: number;
+    line: number;
+    attrs: Map<string, StaticValue>;
+    /** Property names of a literal `style={{...}}` object, when there is one. */
+    styleKeys?: string[];
+    /** CSS variables set in `style` or `vars` to a literal colour, like '--panel': 'rgb(39 39 42)'. */
+    colorVars?: {
+        attr: string;
+        name: string;
+        value: string;
+    }[];
+    /** Source text of the onClick handler, if any. */
+    handlerText?: string;
+    /** Plain text directly inside the element. */
+    childText?: string;
+};
+export type FileAnalysis = {
+    sites: JsxSite[];
+    lines: string[];
+};
+/** A colour written as a value: #rrggbb, rgb(), hsl(), oklch()... */
+export declare const COLOR_LITERAL: RegExp;
+export declare function analyzeFile(file: SourceFile, componentsDir: string): FileAnalysis;
+/** True when one of the two lines above `line` (or the line itself) has `prongs-<marker>: <reason>`. */
+export declare function hasMarker(analysis: FileAnalysis, line: number, marker: 'unsafe' | 'ignore'): boolean;

package/dist/tooling/analyze.js

@@ -0,0 +1,175 @@
+import ts from 'typescript';
+import { COMPONENT_NAMES } from '../vocabulary.js';
+const CLASS_HELPERS = new Set(['cn', 'clsx', 'cx', 'classNames', 'twMerge', 'twJoin']);
+function staticStrings(expr) {
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))
+        return [expr.text];
+    if (ts.isParenthesizedExpression(expr))
+        return staticStrings(expr.expression);
+    if (ts.isConditionalExpression(expr)) {
+        const a = staticStrings(expr.whenTrue);
+        const b = staticStrings(expr.whenFalse);
+        return a && b ? [...a, ...b] : null;
+    }
+    if (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+        return staticStrings(expr.right);
+    }
+    return null;
+}
+/** Class strings from a className value: literals, ternaries and cn()/clsx() string arguments. */
+function classStrings(expr) {
+    const direct = staticStrings(expr);
+    if (direct)
+        return [direct.join(' ')];
+    if (ts.isCallExpression(expr) && ts.isIdentifier(expr.expression) && CLASS_HELPERS.has(expr.expression.text)) {
+        const parts = expr.arguments.flatMap((arg) => staticStrings(arg) ?? []);
+        return parts.length ? [parts.join(' ')] : null;
+    }
+    if (ts.isTemplateExpression(expr)) {
+        const parts = [expr.head.text, ...expr.templateSpans.map((s) => s.literal.text)];
+        return [parts.join(' ')];
+    }
+    return null;
+}
+/** A colour written as a value: #rrggbb, rgb(), hsl(), oklch()... */
+export const COLOR_LITERAL = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
+/** `{...}`, also when wrapped in parentheses or `as` / `satisfies`. */
+function unwrapObject(expr) {
+    let current = expr;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current))
+        current = current.expression;
+    return ts.isObjectLiteralExpression(current) ? current : undefined;
+}
+function attrValue(name, init) {
+    if (!init)
+        return { kind: 'strings', values: ['true'] };
+    if (ts.isStringLiteral(init))
+        return { kind: 'strings', values: [init.text] };
+    if (ts.isJsxExpression(init) && init.expression) {
+        const values = name.toLowerCase().includes('classname')
+            ? classStrings(init.expression)
+            : staticStrings(init.expression);
+        return values ? { kind: 'strings', values } : { kind: 'dynamic' };
+    }
+    return { kind: 'dynamic' };
+}
+function isComponentsImport(specifier, fromPath, componentsDir) {
+    const dir = componentsDir.replace(/\/+$/, '');
+    if (specifier.startsWith('.')) {
+        const base = fromPath.split('/').slice(0, -1);
+        for (const part of specifier.split('/')) {
+            if (part === '..')
+                base.pop();
+            else if (part !== '.')
+                base.push(part);
+        }
+        const resolved = base.join('/');
+        return resolved === dir || resolved.startsWith(dir + '/');
+    }
+    // Path aliases such as "@/components/prongs/Text": match on the directory's trailing segments.
+    const tail = dir.split('/').slice(-2).join('/');
+    return specifier.includes(tail + '/') || specifier.endsWith(tail);
+}
+const cache = new WeakMap();
+export function analyzeFile(file, componentsDir) {
+    const cached = cache.get(file);
+    if (cached)
+        return cached;
+    const kind = file.path.endsWith('.jsx') ? ts.ScriptKind.JSX : ts.ScriptKind.TSX;
+    const source = ts.createSourceFile(file.path, file.text, ts.ScriptTarget.Latest, true, kind);
+    const components = new Map();
+    const nextLinks = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const specifier = statement.moduleSpecifier.text;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        if (specifier === 'next/link' && clause.name)
+            nextLinks.add(clause.name.text);
+        if (!isComponentsImport(specifier, file.path, componentsDir))
+            continue;
+        const named = clause.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings.elements : [];
+        for (const element of named) {
+            const imported = (element.propertyName ?? element.name).text;
+            if (COMPONENT_NAMES.includes(imported))
+                components.set(element.name.text, imported);
+        }
+        if (clause.name && COMPONENT_NAMES.includes(clause.name.text)) {
+            components.set(clause.name.text, clause.name.text);
+        }
+    }
+    const sites = [];
+    const visit = (node) => {
+        const opening = ts.isJsxElement(node) ? node.openingElement : ts.isJsxSelfClosingElement(node) ? node : null;
+        if (opening) {
+            const tag = opening.tagName.getText(source);
+            const attrs = new Map();
+            let styleKeys;
+            let handlerText;
+            const colorVars = [];
+            for (const prop of opening.attributes.properties) {
+                if (!ts.isJsxAttribute(prop))
+                    continue;
+                const name = prop.name.getText(source);
+                attrs.set(name, attrValue(name, prop.initializer));
+                const expr = prop.initializer && ts.isJsxExpression(prop.initializer) ? prop.initializer.expression : undefined;
+                const object = expr ? unwrapObject(expr) : undefined;
+                if (name === 'style' && object) {
+                    styleKeys = object.properties.flatMap((p) => p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) ? [p.name.text] : []);
+                }
+                if ((name === 'style' || name === 'vars') && object) {
+                    for (const p of object.properties) {
+                        if (!ts.isPropertyAssignment(p) || !ts.isStringLiteral(p.name) || !p.name.text.startsWith('--'))
+                            continue;
+                        for (const value of staticStrings(p.initializer) ?? []) {
+                            if (COLOR_LITERAL.test(value))
+                                colorVars.push({ attr: name, name: p.name.text, value });
+                        }
+                    }
+                }
+                if (name === 'onClick' && expr)
+                    handlerText = expr.getText(source).slice(0, 200);
+            }
+            // Plain text and literal strings in {...} children (both branches of a ternary).
+            const childText = ts.isJsxElement(node)
+                ? node.children
+                    .flatMap((c) => ts.isJsxText(c)
+                    ? [c.text.trim()]
+                    : ts.isJsxExpression(c) && c.expression
+                        ? staticStrings(c.expression) ?? []
+                        : [])
+                    .filter(Boolean)
+                    .join(' ')
+                : undefined;
+            const offset = opening.getStart(source);
+            sites.push({
+                tag,
+                component: components.get(tag),
+                nextLink: nextLinks.has(tag),
+                offset,
+                line: source.getLineAndCharacterOfPosition(offset).line + 1,
+                attrs,
+                styleKeys,
+                colorVars: colorVars.length ? colorVars : undefined,
+                handlerText,
+                childText: childText || undefined,
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    const analysis = { sites, lines: file.text.split('\n') };
+    cache.set(file, analysis);
+    return analysis;
+}
+/** True when one of the two lines above `line` (or the line itself) has `prongs-<marker>: <reason>`. */
+export function hasMarker(analysis, line, marker) {
+    const pattern = new RegExp(`prongs-${marker}:\\s*\\S`);
+    for (let l = Math.max(1, line - 2); l <= line; l++) {
+        if (pattern.test(analysis.lines[l - 1] ?? ''))
+            return true;
+    }
+    return false;
+}

package/dist/tooling/components.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentName } from '../vocabulary.js';
+/**
+ * What each component takes and the rules for using it: the source for the "Component props"
+ * section of PRONGS.md and for component reference pages. It describes the components that
+ * `prongs add` copies; a project that changes them can change this too.
+ */
+export type PropDoc = {
+    name: string;
+    type: string;
+    description: string;
+    required?: boolean;
+};
+export type ComponentDoc = {
+    /** What the component is for, in one or two sentences. */
+    summary: string;
+    /** Whether it takes the shared layout props (align, width, ...). */
+    layoutProps: boolean;
+    /** Its own props, most used first. Element attributes it passes through are not listed. */
+    props: readonly PropDoc[];
+    rules: readonly string[];
+};
+/** Where an element sits, never how it looks. Spacing between elements comes from the parent <Layout>. */
+export declare const LAYOUT_PROPS: readonly PropDoc[];
+export declare const COMPONENT_DOCS: Record<ComponentName, ComponentDoc>;