dslinter 0.1.13 → 0.2.0

package/src/components/PlaygroundA11yAndCode.tsx

@@ -1,7 +1,12 @@
 import { useCallback } from "react";
-import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+import type {
+  PlaygroundArgs,
+  PlaygroundControl,
+  PlaygroundValuesUpdater,
+} from "../types/controls";
 import type { PlaygroundEntry } from "../types/playground";
 import type { A11yModuleSummary } from "../report/a11yForModule";
+import type { PlaygroundA11yFinding } from "../playground/scanVariantA11y";
 import type { CodeScoreModuleSummary } from "../report/codeScoreForModule";
 import type { LintFinding, UsageSummary } from "../types/report";
 import { Badge } from "./ui/badge";
@@ -27,16 +32,10 @@ type UsageProps = {
 };
 
 export function PlaygroundUsageSection({ entry, values }: UsageProps) {
-  const usage =
-    entry.usageSnippet?.(values) ??
-    `// Pass usageSnippet on this PlaygroundEntry, or derive snippets from dslint controls.\n<${entry.id} />`;
+  const usage = entry.usageSnippet?.(values) ?? `<${entry.id} />`;
 
   return (
-    <Section
-      id="usage"
-      title="Usage"
-      description="Example usage for the current playground values."
-    >
+    <Section id="usage" title="Usage">
       <PlaygroundUsageCode source={usage} />
     </Section>
   );
@@ -90,7 +89,7 @@ export function PlaygroundTokenStyleSection({
       ) : (
         <EmptyCard>
           Token findings update when{" "}
-          <span className="font-mono">dslint-report.json</span> is available
+          <span className="font-mono">dslinter-report.json</span> is available
           (same fetch as Governance).
         </EmptyCard>
       )}
@@ -143,7 +142,7 @@ export function PlaygroundCodeScoreSection({
       ) : (
         <EmptyCard>
           Code score updates when{" "}
-          <span className="font-mono">dslint-report.json</span> is available
+          <span className="font-mono">dslinter-report.json</span> is available
           (same fetch as Governance).
         </EmptyCard>
       )}
@@ -152,12 +151,22 @@ export function PlaygroundCodeScoreSection({
 }
 
 type A11yProps = {
-  a11y: A11yModuleSummary;
+  a11y: Omit<A11yModuleSummary, "findings"> & {
+    findings: PlaygroundA11yFinding[];
+  };
   reportReady: boolean;
+  variantScanPending?: boolean;
 };
 
-export function PlaygroundA11ySection({ a11y, reportReady }: A11yProps) {
+export function PlaygroundA11ySection({
+  a11y,
+  reportReady,
+  variantScanPending = false,
+}: A11yProps) {
   const hasFindingRows = reportReady && a11y.findings.length > 0;
+  const showVariantColumn = a11y.findings.some(
+    (f) => f.variant_label != null && f.variant_label !== "",
+  );
 
   return (
     <>
@@ -165,6 +174,7 @@ export function PlaygroundA11ySection({ a11y, reportReady }: A11yProps) {
         <Table>
           <TableHeader>
             <TableRow>
+              {showVariantColumn ? <TableHead>Variant</TableHead> : null}
               <TableHead>Rule</TableHead>
               <TableHead>Line</TableHead>
               <TableHead>Severity</TableHead>
@@ -173,7 +183,14 @@ export function PlaygroundA11ySection({ a11y, reportReady }: A11yProps) {
           </TableHeader>
           <TableBody>
             {a11y.findings.map((f, i) => (
-              <TableRow key={`${f.rule_id}-${f.line ?? "x"}-${i}`}>
+              <TableRow
+                key={`${f.rule_id}-${f.line ?? "x"}-${f.variant_label ?? ""}-${i}`}
+              >
+                {showVariantColumn ? (
+                  <TableCell className="font-mono text-xs text-muted-foreground">
+                    {f.variant_label ?? "—"}
+                  </TableCell>
+                ) : null}
                 <TableCell>{f.rule_id}</TableCell>
                 <TableCell>{f.line ?? "—"}</TableCell>
                 <TableCell>{f.severity}</TableCell>
@@ -184,12 +201,14 @@ export function PlaygroundA11ySection({ a11y, reportReady }: A11yProps) {
         </Table>
       ) : reportReady && a11y.issueCount === 0 ? (
         <EmptyCard>
-          No accessibility findings on this file in the current report.
+          {variantScanPending
+            ? "Scanning variant previews for color contrast…"
+            : "No accessibility findings on this file or its variant previews in the current report."}
         </EmptyCard>
       ) : (
         <EmptyCard>
           A11y score updates when{" "}
-          <span className="font-mono">dslint-report.json</span> is available
+          <span className="font-mono">dslinter-report.json</span> is available
           (same fetch as Governance).
         </EmptyCard>
       )}
@@ -198,15 +217,16 @@ export function PlaygroundA11ySection({ a11y, reportReady }: A11yProps) {
 }
 
 type ApiProps = {
+  entry: PlaygroundEntry;
   controls: PlaygroundControl[];
   values: PlaygroundArgs;
-  onChange: (next: PlaygroundArgs) => void;
+  onChange: PlaygroundValuesUpdater;
   onReset: () => void;
   /** When set, adds columns for how often each prop appears at scanned JSX call sites. */
   reportUsage?: UsageSummary;
   /** Declared prop names from the scan (definitions + playground specs), used for “never passed” hints. */
   declaredPropsFromScan?: string[];
-  /** True when `dslint-report.json` is loaded (even if this component has no usage row). */
+  /** True when `dslinter-report.json` is loaded (even if this component has no usage row). */
   governanceReportLoaded?: boolean;
 };
 
@@ -237,9 +257,9 @@ export function PlaygroundApiReference({
 
   const patch = useCallback(
     (key: string, value: string | number | boolean) => {
-      onChange({ ...values, [key]: value });
+      onChange((prev) => ({ ...prev, [key]: value }));
     },
-    [onChange, values],
+    [onChange],
   );
 
   const rows = controlsToApiRows(controls);
@@ -252,12 +272,13 @@ export function PlaygroundApiReference({
         .filter((k) => !controlKeys.has(k))
         .sort((a, b) => a.localeCompare(b))
     : [];
-
+  const repoUsageProps = showRepo
+    ? [...rows.map((r) => r.prop), ...extraRepoProps]
+    : [];
   return (
     <Section
       id="api-reference"
       title="API reference"
-      description=""
       actions={
         <Button type="button" variant="outline" size="sm" onClick={onReset}>
           Reset defaults
@@ -270,20 +291,12 @@ export function PlaygroundApiReference({
             <TableHead>Prop</TableHead>
             <TableHead>Type</TableHead>
             <TableHead>Value</TableHead>
-            {showRepo ? (
-              <>
-                <TableHead>Usage</TableHead>
-                <TableHead>Values</TableHead>
-              </>
-            ) : null}
           </TableRow>
         </TableHeader>
         <TableBody>
           {controls.map((c) => {
             const r = rows.find((row) => row.prop === c.key);
             if (!r) return null;
-            const n = showRepo ? (freqs[r.prop] ?? 0) : 0;
-            const valueChips = formatRepoLiteralChips(valueFreqs[r.prop]);
             return (
               <TableRow key={r.prop}>
                 <TableCell className="font-medium">{r.prop}</TableCell>
@@ -322,9 +335,9 @@ export function PlaygroundApiReference({
                   ) : (
                     <span className="font-mono text-xs flex items-center gap-1">
                       {r.type}
-                      {r.default !== "—" ? (
+                      {r.defaultBadge ? (
                         <Badge variant="secondary" size="sm">
-                          {r.default}
+                          {r.defaultBadge}
                         </Badge>
                       ) : null}
                     </span>
@@ -339,40 +352,27 @@ export function PlaygroundApiReference({
                     layout="table"
                   />
                 </TableCell>
-                {showRepo ? (
-                  <>
-                    <TableCell>{n}</TableCell>
-                    <TableCell>{valueChips}</TableCell>
-                  </>
-                ) : null}
               </TableRow>
             );
           })}
         </TableBody>
       </Table>
 
-      {showRepo && extraRepoProps.length > 0 ? (
-        <div className="mt-4">
-          <h3 className="text-sm font-semibold text-foreground">
-            Also seen in repo (not in playground)
-          </h3>
-          <p className="mt-1 text-xs text-muted-foreground">
-            These prop names appear in scanned JSX but are not wired as
-            playground controls on this page.
-          </p>
+      {showRepo ? (
+        <Section id="repo-usage" title="Repo usage" className="mt-4">
           <Table>
             <TableHeader>
               <TableRow>
                 <TableHead>Prop</TableHead>
-                <TableHead>Repo call sites</TableHead>
-                <TableHead>Repo literals</TableHead>
+                <TableHead>Count</TableHead>
+                <TableHead>Values</TableHead>
               </TableRow>
             </TableHeader>
             <TableBody>
-              {extraRepoProps.map((prop) => (
+              {repoUsageProps.map((prop) => (
                 <TableRow key={prop}>
-                  <TableCell>{prop}</TableCell>
-                  <TableCell>×{freqs[prop] ?? 0}</TableCell>
+                  <TableCell className="font-medium">{prop}</TableCell>
+                  <TableCell>{freqs[prop] ?? 0}</TableCell>
                   <TableCell>
                     {formatRepoLiteralChips(valueFreqs[prop])}
                   </TableCell>
@@ -380,7 +380,7 @@ export function PlaygroundApiReference({
               ))}
             </TableBody>
           </Table>
-        </div>
+        </Section>
       ) : null}
     </Section>
   );

package/src/components/PlaygroundAppThemeWrapper.tsx

@@ -0,0 +1,82 @@
+import { forwardRef, useMemo, type CSSProperties, type ReactNode } from "react";
+import type { WorkspaceReport } from "../types/report";
+import {
+  buildAppPreviewThemeFromReport,
+  cssVariablesForPreviewTheme,
+} from "../playground/appPreviewTheme";
+import { useDashboardTheme } from "../shell/DashboardLayout";
+import { cn } from "../lib/utils";
+
+type Props = {
+  children: ReactNode;
+  workspaceReport: WorkspaceReport | null;
+  className?: string;
+};
+
+export const PlaygroundAppThemeWrapper = forwardRef<HTMLDivElement, Props>(
+  function PlaygroundAppThemeWrapper(
+    { children, workspaceReport, className },
+    ref,
+  ) {
+    const { resolvedTheme } = useDashboardTheme();
+    const previewTheme = useMemo(
+      () => buildAppPreviewThemeFromReport(workspaceReport),
+      [workspaceReport],
+    );
+    const isDark = resolvedTheme === "dark";
+    const hasDarkTokens =
+      previewTheme != null && Object.keys(previewTheme.dark).length > 0;
+
+    if (!previewTheme) {
+      return (
+        <div
+          ref={ref}
+          className={cn(isDark && "dark", className)}
+          data-app-preview-theme={resolvedTheme}
+        >
+          {children}
+        </div>
+      );
+    }
+
+    // App CSS has light tokens only — don't inject them in dark mode; inherit
+    // dashboard dark tokens from the surrounding [data-dashboard-theme] tree.
+    if (isDark && !hasDarkTokens) {
+      return (
+        <div
+          ref={ref}
+          className={cn("ds-playground-app-preview", className)}
+          data-app-preview-theme={resolvedTheme}
+        >
+          {children}
+        </div>
+      );
+    }
+
+    const vars = cssVariablesForPreviewTheme(
+      previewTheme,
+      isDark ? "dark" : "light",
+    );
+    const usesDarkTokens = isDark && hasDarkTokens;
+
+    const style = {
+      ...vars,
+      colorScheme: usesDarkTokens ? "dark" : "light",
+    } as CSSProperties;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "ds-playground-app-preview",
+          isDark && "dark",
+          className,
+        )}
+        style={style}
+        data-app-preview-theme={resolvedTheme}
+      >
+        {children}
+      </div>
+    );
+  },
+);

package/src/components/PlaygroundControls.tsx

@@ -1,29 +1,23 @@
 import { useCallback } from "react";
-import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+import type { PlaygroundArgs, PlaygroundControl, PlaygroundValuesUpdater } from "../types/controls";
 import { Button } from "./ui/button";
 import { PlaygroundControlField } from "./PlaygroundControlField";
 
 type Props = {
   controls: PlaygroundControl[];
   values: PlaygroundArgs;
-  onChange: (next: PlaygroundArgs) => void;
+  onChange: PlaygroundValuesUpdater;
   onReset: () => void;
   /** Omit the outer card wrapper (doc-style pages provide their own section chrome). */
   bare?: boolean;
 };
 
-export function PlaygroundControls({
-  controls,
-  values,
-  onChange,
-  onReset,
-  bare,
-}: Props) {
+export function PlaygroundControls({ controls, values, onChange, onReset, bare }: Props) {
   const patch = useCallback(
     (key: string, value: string | number | boolean) => {
-      onChange({ ...values, [key]: value });
+      onChange((prev) => ({ ...prev, [key]: value }));
     },
-    [onChange, values],
+    [onChange],
   );
 
   if (controls.length === 0) return null;

package/src/components/PlaygroundPreviewErrorBoundary.tsx

@@ -0,0 +1,54 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+type Props = {
+  children: ReactNode;
+  componentName?: string;
+};
+
+type State = {
+  error: Error | null;
+};
+
+export class PlaygroundPreviewErrorBoundary extends Component<Props, State> {
+  state: State = { error: null };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    if (process.env.NODE_ENV === "development") {
+      console.warn(
+        "[dslinter] preview render failed",
+        error,
+        info.componentStack,
+      );
+    }
+  }
+
+  componentDidUpdate(prevProps: Props) {
+    if (prevProps.children !== this.props.children && this.state.error) {
+      this.setState({ error: null });
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      const name = this.props.componentName ?? "Component";
+      return (
+        <div className="rounded-md border border-border bg-muted/40 px-4 py-6 text-sm text-muted-foreground">
+          <p className="font-medium text-foreground">
+            Preview could not render {name}
+          </p>
+          <p className="mt-2">
+            This component may need Inertia page props, a provider, or other app
+            context. The scanner snapshot and governance panels still reflect
+            static analysis.
+          </p>
+          <p className="mt-2 font-mono text-xs">{this.state.error.message}</p>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}

package/src/components/PlaygroundUsageCode.tsx

@@ -1,18 +1,20 @@
 import { useEffect, useRef, useState } from "react";
+import { useDashboardTheme } from "../shell/DashboardLayout";
 import { renderPlaygroundUsageHtml } from "./playgroundUsageHighlight";
 
 const shellClass =
-  "playground-usage-shiki mt-4 overflow-x-auto rounded-lg border bg-gray-900 p-4 text-sm leading-relaxed shadow-xs " +
+  "playground-usage-shiki mt-4 overflow-x-auto rounded-lg border border-border p-4 text-sm leading-relaxed text-foreground " +
   "[&_.shiki]:!bg-transparent [&_pre.shiki]:!m-0 [&_pre.shiki]:!bg-transparent [&_pre.shiki]:!p-0";
 
 const plainPreClass =
-  "m-0 whitespace-pre font-mono text-sm leading-relaxed text-gray-100";
+  "m-0 whitespace-pre font-mono text-sm leading-relaxed text-foreground";
 
 type Props = {
   source: string;
 };
 
 export function PlaygroundUsageCode({ source }: Props) {
+  const { theme } = useDashboardTheme();
   const [html, setHtml] = useState<string | null>(null);
   const seq = useRef(0);
 
@@ -23,7 +25,7 @@ export function PlaygroundUsageCode({ source }: Props) {
 
     void (async () => {
       try {
-        const next = await renderPlaygroundUsageHtml(source, ac.signal);
+        const next = await renderPlaygroundUsageHtml(source, theme, ac.signal);
         if (id !== seq.current) return;
         setHtml(next);
       } catch (e) {
@@ -34,7 +36,7 @@ export function PlaygroundUsageCode({ source }: Props) {
     })();
 
     return () => ac.abort();
-  }, [source]);
+  }, [source, theme]);
 
   if (html) {
     return (

package/src/components/PlaygroundVariantMatrix.tsx

@@ -1,14 +1,20 @@
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
 import type { PlaygroundArgs } from "../types/controls";
-import type { PlaygroundPreviewComponent } from "../types/preview";
+import {
+  scanVariantPreviews,
+  type PlaygroundA11yFinding,
+} from "../playground/scanVariantA11y";
 import { Badge } from "./ui/badge";
 import { PLAYGROUND_VARIANT_MATRIX_CAP } from "../playground/enumerateControlCombinations";
 
 type Props = {
-  Preview: PlaygroundPreviewComponent;
+  renderPreview: (values: PlaygroundArgs) => ReactNode;
   combinations: PlaygroundArgs[];
   finiteAxisKeys: string[];
   totalCount: number;
   capped: boolean;
+  onVariantA11yScan?: (findings: PlaygroundA11yFinding[]) => void;
 };
 
 function formatValue(value: string | number | boolean): string {
@@ -16,52 +22,113 @@ function formatValue(value: string | number | boolean): string {
   return JSON.stringify(value);
 }
 
+function variantKey(combo: PlaygroundArgs, axisKeys: string[]): string {
+  return axisKeys.map((k) => `${k}:${formatValue(combo[k] ?? "")}`).join("|");
+}
+
 export function PlaygroundVariantMatrix({
-  Preview,
+  renderPreview,
   combinations,
   finiteAxisKeys,
   totalCount,
   capped,
+  onVariantA11yScan,
 }: Props) {
-  if (combinations.length === 0) return null;
+  const previewRefs = useRef(new Map<string, HTMLDivElement>());
+
+  const visibleCombinations = combinations.filter(
+    (combo) => combo.asChild !== true,
+  );
+  const visibleAxisKeys = finiteAxisKeys.filter((key) => key !== "asChild");
+  const skipsAsChildAxis = finiteAxisKeys.includes("asChild");
+  const adjustedTotalCount = skipsAsChildAxis
+    ? Math.ceil(totalCount / 2)
+    : totalCount;
+
+  useEffect(() => {
+    if (!onVariantA11yScan || visibleCombinations.length === 0) return;
+
+    let cancelled = false;
+    const frameId = requestAnimationFrame(() => {
+      void (async () => {
+        await new Promise<void>((resolve) => {
+          requestAnimationFrame(() => resolve());
+        });
+        if (cancelled) return;
+
+        const targets = visibleCombinations.flatMap((combo) => {
+          const key = variantKey(combo, visibleAxisKeys);
+          const element = previewRefs.current.get(key);
+          if (!element) return [];
+          return [{ element, combo, axisKeys: visibleAxisKeys }];
+        });
+
+        if (targets.length === 0) {
+          if (!cancelled) onVariantA11yScan([]);
+          return;
+        }
+
+        try {
+          const findings = await scanVariantPreviews(targets);
+          if (!cancelled) onVariantA11yScan(findings);
+        } catch {
+          if (!cancelled) onVariantA11yScan([]);
+        }
+      })();
+    });
+
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frameId);
+    };
+  }, [onVariantA11yScan, visibleCombinations, visibleAxisKeys]);
+
+  if (visibleCombinations.length === 0) return null;
 
   return (
     <>
       {capped ? (
-        <p className="rounded-md border border-border bg-muted/60 px-3 py-2 text-sm text-muted-foreground">
-          Showing {combinations.length} of {totalCount} combinations (limit{" "}
-          {PLAYGROUND_VARIANT_MATRIX_CAP}). Reduce select options or split
-          controls to preview more here.
+        <p className="rounded-md border border-border  px-3 py-2 text-sm text-muted-foreground">
+          Showing {visibleCombinations.length} of {adjustedTotalCount}{" "}
+          combinations (limit {PLAYGROUND_VARIANT_MATRIX_CAP}). Reduce select
+          options or split controls to preview more here.
         </p>
       ) : null}
       <div className="mt-4 flex flex-col gap-4">
-        {combinations.map((combo) => (
-          <div
-            key={finiteAxisKeys
-              .map((k) => `${k}:${formatValue(combo[k] ?? "")}`)
-              .join("|")}
-            className="flex min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-xs"
-          >
-            <div className="flex flex-wrap gap-1 border-b p-2">
-              {finiteAxisKeys.map((k) => {
-                const v = combo[k];
-                return (
-                  <Badge
-                    key={k}
-                    variant="outline"
-                    size="sm"
-                    className="font-mono text-xs"
-                  >
-                    {k}={v === undefined ? "?" : formatValue(v)}
-                  </Badge>
-                );
-              })}
-            </div>
-            <div className="min-w-0 bg-card p-3">
-              <Preview values={combo} />
+        {visibleCombinations.map((combo) => {
+          const key = variantKey(combo, visibleAxisKeys);
+          return (
+            <div
+              key={key}
+              className="flex min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-xs"
+            >
+              <div className="flex flex-wrap gap-1 border-b p-2">
+                {visibleAxisKeys.map((k) => {
+                  const v = combo[k];
+                  return (
+                    <Badge
+                      key={k}
+                      variant="outline"
+                      size="sm"
+                      className="font-mono text-xs"
+                    >
+                      {k}={v === undefined ? "?" : formatValue(v)}
+                    </Badge>
+                  );
+                })}
+              </div>
+              <div
+                ref={(el) => {
+                  if (el) previewRefs.current.set(key, el);
+                  else previewRefs.current.delete(key);
+                }}
+                className="min-w-0 p-3"
+              >
+                {renderPreview(combo)}
+              </div>
             </div>
-          </div>
-        ))}
+          );
+        })}
       </div>
     </>
   );

package/src/components/Section.tsx

@@ -1,20 +1,23 @@
 import type { ReactNode } from "react";
+import { cn } from "../lib/utils";
 
 export function Section({
   id,
+  className,
   children,
   title,
   description,
   actions,
 }: {
   id: string;
+  className?: string;
   children: ReactNode;
   title: string;
-  description: string;
+  description?: string;
   actions?: ReactNode;
 }) {
   return (
-    <section id={id} className="scroll-mt-20">
+    <section id={id} className={cn("scroll-mt-20", className)}>
       <div className="flex items-center justify-between gap-2">
         <div>
           <h2 className="text-lg/none font-semibold tracking-tight text-foreground">