@polymorfa/devtools 0.1.0-dev.20260922094209

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Polymorfa
+
+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

@@ -0,0 +1,41 @@
+# `@polymorfa/devtools`
+
+An explicit development assistant for testing Polymorfa appearance, direction,
+motion, viewport presets, network profiles, and redacted request diagnostics.
+
+The assistant only enables when a trusted build environment and the client-token
+environment match and both are non-production. URL query parameters are never
+consulted. The `@polymorfa/devtools/production` entry point is inert.
+
+```ts
+import { DevAssistant, mountDevAssistant } from "@polymorfa/devtools";
+
+const assistant = new DevAssistant({
+  environment: "development",
+  tokenEnvironment: "development",
+});
+
+mountDevAssistant(assistant);
+```
+
+The assistant starts as a 40px launcher button in the bottom-left corner, so
+it stays clear of a chat composer. Selecting it opens the panel beside it;
+Escape or the close button closes the panel and returns focus to the
+launcher. The open state is kept in `sessionStorage` for the tab when
+storage is available. The launcher and panel render in a shadow root, follow
+the system light or dark color scheme, and skip their transitions when
+reduced motion is preferred.
+
+```ts
+const mounted = mountDevAssistant(assistant, {
+  position: "top-right", // "bottom-left" (default), "bottom-right", "top-left"
+  defaultOpen: false,
+  offset: { x: 16, y: 16 },
+  parent: document.body,
+});
+mounted?.open();
+mounted?.dispose();
+```
+
+Passing a parent element as the second argument still works. The returned
+`element` is the host; the controls are inside its open `shadowRoot`.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DevAssistant, type DevAssistantOptions, type DevAssistantSettings, type DevAssistantSnapshot, type NetworkProfile, type RuntimeEnvironment, type ViewportPreset, } from "./model.js";
+export { createSimulatedFetch, type SimulatedFetchOptions } from "./network.js";
+export { mountDevAssistant, type DevAssistantPosition, type MountDevAssistantOptions, type MountedDevAssistant, } from "./panel.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EACL,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DevAssistant, } from "./model.js";
+export { createSimulatedFetch } from "./network.js";
+export { mountDevAssistant, } from "./panel.js";

package/dist/model.d.ts

@@ -0,0 +1,44 @@
+import type { BrowserDiagnosticEvent } from "@polymorfa/browser";
+import { type Appearance, type AppearanceInput, type Direction, type MotionPreference, type Theme } from "@polymorfa/ui";
+export type RuntimeEnvironment = "development" | "test" | "preview" | "production";
+export type NetworkProfile = "online" | "slow" | "offline";
+export type ViewportPreset = "responsive" | "mobile" | "tablet" | "desktop";
+export interface DevAssistantSettings {
+    readonly appearance: Appearance;
+    readonly locale: string;
+    readonly direction: Direction;
+    readonly motion: MotionPreference;
+    readonly viewport: ViewportPreset;
+    readonly network: NetworkProfile;
+}
+export interface DevAssistantOptions {
+    /** Must come from trusted build or server configuration, never the URL. */
+    readonly environment: RuntimeEnvironment;
+    /** Environment asserted by the client-token minting service. */
+    readonly tokenEnvironment: RuntimeEnvironment;
+    readonly appearance?: AppearanceInput;
+    readonly locale?: string;
+    readonly maxEvents?: number;
+}
+export interface DevAssistantSnapshot extends DevAssistantSettings {
+    readonly enabled: boolean;
+    readonly events: readonly unknown[];
+}
+export declare class DevAssistant {
+    #private;
+    constructor(options: DevAssistantOptions);
+    getSnapshot: () => DevAssistantSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    diagnosticSink: (event: BrowserDiagnosticEvent) => void;
+    configure(input: {
+        readonly theme?: Theme;
+        readonly locale?: string;
+        readonly direction?: Direction;
+        readonly motion?: MotionPreference;
+        readonly viewport?: ViewportPreset;
+        readonly network?: NetworkProfile;
+    }): void;
+    copyableConfig(): string;
+    clearEvents(): void;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,kBAAkB,GAC5B,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AAED,qBAAa,YAAY;;gBAOX,OAAO,EAAE,mBAAmB;IAiBxC,WAAW,QAAO,oBAAoB,CAKjC;IAEL,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG9C;IAEF,cAAc,GAAI,OAAO,sBAAsB,KAAG,IAAI,CAMpD;IAEF,SAAS,CAAC,KAAK,EAAE;QACf,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;QAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;QACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;QACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;KACnC,GAAG,IAAI;IA2BR,cAAc,IAAI,MAAM;IAIxB,WAAW,IAAI,IAAI;CASpB"}

package/dist/model.js

@@ -0,0 +1,79 @@
+import { defineAppearance, redactDiagnostic, } from "@polymorfa/ui";
+export class DevAssistant {
+    #enabled;
+    #maxEvents;
+    #listeners = new Set();
+    #settings;
+    #events = [];
+    constructor(options) {
+        this.#enabled =
+            options.environment !== "production" &&
+                options.tokenEnvironment !== "production" &&
+                options.environment === options.tokenEnvironment;
+        this.#maxEvents = Math.max(1, Math.floor(options.maxEvents ?? 50));
+        const appearance = defineAppearance(options.appearance);
+        this.#settings = Object.freeze({
+            appearance,
+            locale: options.locale ?? "en",
+            direction: appearance.layout.direction,
+            motion: appearance.variables.motion,
+            viewport: "responsive",
+            network: "online",
+        });
+    }
+    getSnapshot = () => Object.freeze({
+        ...this.#settings,
+        enabled: this.#enabled,
+        events: Object.freeze([...this.#events]),
+    });
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    };
+    diagnosticSink = (event) => {
+        if (!this.#enabled)
+            return;
+        this.#events = [...this.#events, redactDiagnostic(event)].slice(-this.#maxEvents);
+        this.#emit();
+    };
+    configure(input) {
+        if (!this.#enabled)
+            return;
+        const appearance = defineAppearance({
+            ...this.#settings.appearance,
+            ...(input.theme === undefined ? {} : { theme: input.theme }),
+            variables: {
+                ...this.#settings.appearance.variables,
+                ...(input.motion === undefined ? {} : { motion: input.motion }),
+            },
+            layout: {
+                ...this.#settings.appearance.layout,
+                ...(input.direction === undefined
+                    ? {}
+                    : { direction: input.direction }),
+            },
+        });
+        this.#settings = Object.freeze({
+            appearance,
+            locale: input.locale ?? this.#settings.locale,
+            direction: input.direction ?? this.#settings.direction,
+            motion: input.motion ?? this.#settings.motion,
+            viewport: input.viewport ?? this.#settings.viewport,
+            network: input.network ?? this.#settings.network,
+        });
+        this.#emit();
+    }
+    copyableConfig() {
+        return JSON.stringify(this.#settings, null, 2);
+    }
+    clearEvents() {
+        if (!this.#enabled)
+            return;
+        this.#events = [];
+        this.#emit();
+    }
+    #emit() {
+        for (const listener of this.#listeners)
+            listener();
+    }
+}

package/dist/network.d.ts

@@ -0,0 +1,9 @@
+import type { NetworkProfile } from "./model.js";
+export interface SimulatedFetchOptions {
+    readonly profile: () => NetworkProfile;
+    readonly delayMs?: number;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** Explicitly wraps fetch for development; no simulation is installed globally. */
+export declare function createSimulatedFetch(options: SimulatedFetchOptions): typeof fetch;
+//# sourceMappingURL=network.d.ts.map

package/dist/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../src/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,cAAc,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAC1C;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,KAAK,CAWd"}

package/dist/network.js

@@ -0,0 +1,26 @@
+/** Explicitly wraps fetch for development; no simulation is installed globally. */
+export function createSimulatedFetch(options) {
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    return async (input, init) => {
+        const profile = options.profile();
+        if (profile === "offline")
+            throw new TypeError("Simulated offline network.");
+        if (profile === "slow") {
+            await abortableDelay(options.delayMs ?? 800, init?.signal);
+        }
+        return fetchImplementation(input, init);
+    };
+}
+function abortableDelay(delayMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(signal.reason);
+            return;
+        }
+        const timeout = setTimeout(resolve, delayMs);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}

package/dist/panel.d.ts

@@ -0,0 +1,31 @@
+import type { DevAssistant } from "./model.js";
+export type DevAssistantPosition = "bottom-left" | "bottom-right" | "top-left" | "top-right";
+export interface MountDevAssistantOptions {
+    /** Corner for the launcher. Defaults to `"bottom-left"`. */
+    readonly position?: DevAssistantPosition;
+    /** Open the panel on first mount. Defaults to `false`. */
+    readonly defaultOpen?: boolean;
+    /** Distance from the viewport edges in pixels. Defaults to 16 each. */
+    readonly offset?: {
+        readonly x?: number;
+        readonly y?: number;
+    };
+    /** Element to mount into. Defaults to `document.body`. */
+    readonly parent?: HTMLElement;
+}
+export interface MountedDevAssistant {
+    /** Host element; the launcher and panel live in its open shadow root. */
+    readonly element: HTMLElement;
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    dispose(): void;
+}
+/**
+ * Mount the development panel: a small launcher in a corner that opens the
+ * panel next to it. Returns `null` when the assistant is disabled. The
+ * second argument may also be the parent element, as in earlier versions.
+ */
+export declare function mountDevAssistant(assistant: DevAssistant, options?: MountDevAssistantOptions | HTMLElement): MountedDevAssistant | null;
+//# sourceMappingURL=panel.d.ts.map

package/dist/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../src/panel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,MAAM,YAAY,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAC9B,aAAa,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB;AAkND;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,YAAY,EACvB,OAAO,GAAE,wBAAwB,GAAG,WAAgB,GACnD,mBAAmB,GAAG,IAAI,CA+K5B"}

package/dist/panel.js

@@ -0,0 +1,407 @@
+const STORAGE_KEY = "polymorfa:devtools:open";
+function readOpen() {
+    try {
+        const value = globalThis.sessionStorage?.getItem(STORAGE_KEY);
+        return value === "1" ? true : value === "0" ? false : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeOpen(open) {
+    try {
+        globalThis.sessionStorage?.setItem(STORAGE_KEY, open ? "1" : "0");
+    }
+    catch {
+        // Storage can be blocked; the state then lasts for this page only.
+    }
+}
+const STYLES = `
+:host {
+  all: initial;
+  --bg: #ffffff;
+  --fg: #17151f;
+  --muted: #6d6878;
+  --border: #e4e1ea;
+  --surface: #f5f4f8;
+  --accent: #5b4bf7;
+  --on-accent: #ffffff;
+  --shadow: 0 24px 60px rgb(23 21 31 / 0.18), 0 2px 8px rgb(23 21 31 / 0.08);
+  position: fixed;
+  z-index: 2147483647;
+  font: 13px/1.45 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  color: var(--fg);
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :host {
+    --bg: #1c1b22;
+    --fg: #f1eff6;
+    --muted: #a19cae;
+    --border: #34313e;
+    --surface: #26242e;
+    --accent: #8b80ff;
+    --on-accent: #120f2b;
+    --shadow: 0 24px 60px rgb(0 0 0 / 0.5), 0 2px 8px rgb(0 0 0 / 0.3);
+    color-scheme: dark;
+  }
+}
+*, *::before, *::after { box-sizing: border-box; }
+button, select { font: inherit; color: inherit; }
+.launcher {
+  display: grid;
+  place-items: center;
+  width: 40px;
+  height: 40px;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 50%;
+  background: var(--bg);
+  color: var(--accent);
+  box-shadow: 0 4px 14px rgb(0 0 0 / 0.16);
+  cursor: pointer;
+  opacity: 0.85;
+  transition: opacity 120ms ease, transform 120ms ease, background-color 120ms ease;
+}
+.launcher:hover, .launcher[aria-expanded="true"] { opacity: 1; }
+.launcher[aria-expanded="true"] { background: var(--accent); color: var(--on-accent); border-color: transparent; }
+.launcher:active { transform: scale(0.94); }
+.launcher svg { width: 20px; height: 20px; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.panel {
+  position: absolute;
+  width: min(320px, calc(100vw - 32px));
+  max-height: min(560px, calc(100vh - 88px));
+  overflow: auto;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: var(--bg);
+  box-shadow: var(--shadow);
+  transform-origin: var(--origin);
+  transition: opacity 140ms ease, transform 140ms ease, visibility 0s linear 140ms;
+}
+.panel[hidden] { display: block; visibility: hidden; opacity: 0; transform: scale(0.96); pointer-events: none; }
+.panel:not([hidden]) { transition-delay: 0s; }
+:host([data-position^="bottom"]) .panel { bottom: 48px; }
+:host([data-position^="top"]) .panel { top: 48px; }
+:host([data-position$="left"]) .panel { left: 0; }
+:host([data-position$="right"]) .panel { right: 0; }
+header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 8px 10px 14px;
+  border-bottom: 1px solid var(--border);
+}
+h2 { flex: 1; margin: 0; font-size: 13px; font-weight: 650; }
+.icon-button {
+  display: grid;
+  place-items: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: none;
+  color: var(--muted);
+  cursor: pointer;
+}
+.icon-button:hover { background: var(--surface); color: var(--fg); }
+.icon-button svg { width: 16px; height: 16px; }
+.body { display: flex; flex-direction: column; gap: 12px; padding: 12px 14px 14px; }
+fieldset { margin: 0; padding: 0; border: 0; min-width: 0; }
+legend, .label { display: block; margin-bottom: 6px; padding: 0; color: var(--muted); font-size: 11px; font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase; }
+.segmented {
+  display: flex;
+  gap: 2px;
+  padding: 2px;
+  border-radius: 9px;
+  background: var(--surface);
+}
+.segmented label { flex: 1; position: relative; }
+.segmented input { position: absolute; inset: 0; margin: 0; opacity: 0; cursor: pointer; }
+.segmented span {
+  display: block;
+  padding: 5px 4px;
+  border-radius: 7px;
+  color: var(--muted);
+  font-weight: 550;
+  text-align: center;
+  text-transform: capitalize;
+  white-space: nowrap;
+  transition: background-color 120ms ease, color 120ms ease;
+}
+.segmented input:checked + span { background: var(--bg); color: var(--fg); box-shadow: 0 1px 2px rgb(0 0 0 / 0.12); }
+.segmented input:focus-visible + span { outline: 2px solid var(--accent); outline-offset: -2px; }
+.select { position: relative; }
+.select select {
+  appearance: none;
+  width: 100%;
+  min-height: 32px;
+  padding: 5px 30px 5px 10px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--surface);
+  text-transform: capitalize;
+  cursor: pointer;
+}
+.select svg { position: absolute; right: 10px; top: 50%; width: 14px; height: 14px; transform: translateY(-50%); color: var(--muted); pointer-events: none; }
+footer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 14px;
+  border-top: 1px solid var(--border);
+  background: var(--surface);
+}
+.events { flex: 1; color: var(--muted); font-size: 12px; font-variant-numeric: tabular-nums; }
+.button {
+  min-height: 32px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: 8px;
+  background: var(--accent);
+  color: var(--on-accent);
+  font-weight: 600;
+  cursor: pointer;
+}
+.button:hover { filter: brightness(1.08); }
+@media (prefers-reduced-motion: reduce) {
+  .launcher, .panel, .segmented span { transition: none; }
+}
+`;
+const SVG = "http://www.w3.org/2000/svg";
+function svgIcon(d) {
+    const svg = document.createElementNS(SVG, "svg");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    svg.setAttribute("aria-hidden", "true");
+    const path = document.createElementNS(SVG, "path");
+    path.setAttribute("d", d);
+    svg.append(path);
+    return svg;
+}
+const ICONS = {
+    wrench: "M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76Z",
+    close: "M18 6 6 18M6 6l12 12",
+    chevron: "m6 9 6 6 6-6",
+};
+let instance = 0;
+function isOptions(value) {
+    return (value !== undefined &&
+        !(typeof HTMLElement !== "undefined" && value instanceof HTMLElement));
+}
+/**
+ * Mount the development panel: a small launcher in a corner that opens the
+ * panel next to it. Returns `null` when the assistant is disabled. The
+ * second argument may also be the parent element, as in earlier versions.
+ */
+export function mountDevAssistant(assistant, options = {}) {
+    if (!assistant.getSnapshot().enabled)
+        return null;
+    const settings = isOptions(options)
+        ? options
+        : { parent: options };
+    const parent = settings.parent ?? document.body;
+    const position = settings.position ?? "bottom-left";
+    const x = settings.offset?.x ?? 16;
+    const y = settings.offset?.y ?? 16;
+    const id = `pmfa-devtools-${++instance}`;
+    const host = document.createElement("div");
+    host.dataset.polymorfaDevtools = "";
+    host.dataset.position = position;
+    const [vertical, horizontal] = position.split("-");
+    host.style.setProperty(vertical, `${y}px`);
+    host.style.setProperty(horizontal, `${x}px`);
+    const shadow = host.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = STYLES;
+    const launcher = document.createElement("button");
+    launcher.type = "button";
+    launcher.className = "launcher";
+    launcher.setAttribute("aria-label", "Polymorfa dev mode");
+    launcher.setAttribute("aria-controls", `${id}-panel`);
+    launcher.title = "Polymorfa dev mode";
+    launcher.append(svgIcon(ICONS.wrench));
+    const panel = document.createElement("section");
+    panel.className = "panel";
+    panel.id = `${id}-panel`;
+    panel.setAttribute("role", "dialog");
+    panel.setAttribute("aria-label", "Polymorfa developer assistant");
+    panel.style.setProperty("--origin", `${vertical} ${horizontal}`);
+    const header = document.createElement("header");
+    const title = document.createElement("h2");
+    title.textContent = "Polymorfa dev mode";
+    const close = document.createElement("button");
+    close.type = "button";
+    close.className = "icon-button";
+    close.setAttribute("aria-label", "Close dev mode");
+    close.append(svgIcon(ICONS.close));
+    header.append(title, close);
+    const body = document.createElement("div");
+    body.className = "body";
+    const controls = [
+        segmented(`${id}-theme`, "Theme", ["system", "light", "dark"], (value) => assistant.configure({ theme: value })),
+        segmented(`${id}-direction`, "Direction", ["auto", "ltr", "rtl"], (value) => assistant.configure({ direction: value })),
+        segmented(`${id}-motion`, "Motion", ["system", "full", "reduced"], (value) => assistant.configure({
+            motion: value,
+        })),
+        select(`${id}-viewport`, "Viewport", ["responsive", "mobile", "tablet", "desktop"], (value) => assistant.configure({
+            viewport: value,
+        })),
+        segmented(`${id}-network`, "Network", ["online", "slow", "offline"], (value) => assistant.configure({
+            network: value,
+        })),
+    ];
+    body.append(...controls.map((control) => control.node));
+    const footer = document.createElement("footer");
+    const events = document.createElement("span");
+    events.className = "events";
+    events.setAttribute("aria-live", "polite");
+    const copy = document.createElement("button");
+    copy.type = "button";
+    copy.className = "button";
+    copy.textContent = "Copy configuration";
+    let copyTimer;
+    copy.addEventListener("click", () => {
+        void navigator.clipboard
+            ?.writeText(assistant.copyableConfig())
+            .then(() => {
+            copy.textContent = "Copied";
+            clearTimeout(copyTimer);
+            copyTimer = setTimeout(() => {
+                copy.textContent = "Copy configuration";
+            }, 1500);
+        })
+            .catch(() => undefined);
+    });
+    footer.append(events, copy);
+    panel.append(header, body, footer);
+    shadow.append(style, panel, launcher);
+    parent.append(host);
+    let isOpen = readOpen() ?? settings.defaultOpen ?? false;
+    const apply = () => {
+        panel.hidden = !isOpen;
+        launcher.setAttribute("aria-expanded", String(isOpen));
+    };
+    const setOpen = (next, focus) => {
+        if (next === isOpen)
+            return;
+        isOpen = next;
+        writeOpen(next);
+        apply();
+        if (!focus)
+            return;
+        if (next)
+            panel
+                .querySelector("input:checked, select, button")
+                ?.focus();
+        else
+            launcher.focus();
+    };
+    apply();
+    // Opening from the launcher moves focus into the panel, which precedes the
+    // launcher in tab order; closing leaves focus on the launcher itself.
+    launcher.addEventListener("click", () => setOpen(!isOpen, true));
+    close.addEventListener("click", () => setOpen(false, true));
+    shadow.addEventListener("keydown", (event) => {
+        const key = event;
+        if (key.key !== "Escape" || !isOpen || key.isComposing)
+            return;
+        key.preventDefault();
+        key.stopPropagation();
+        setOpen(false, true);
+    });
+    const render = () => {
+        const snapshot = assistant.getSnapshot();
+        panel.dir = snapshot.direction === "rtl" ? "rtl" : "ltr";
+        const values = [
+            snapshot.appearance.theme,
+            snapshot.direction,
+            snapshot.motion,
+            snapshot.viewport,
+            snapshot.network,
+        ];
+        controls.forEach((control, index) => control.set(values[index] ?? ""));
+        const count = snapshot.events.length;
+        events.textContent = `${count} redacted request event${count === 1 ? "" : "s"}`;
+    };
+    const unsubscribe = assistant.subscribe(render);
+    render();
+    return {
+        element: host,
+        get isOpen() {
+            return isOpen;
+        },
+        open: () => setOpen(true, false),
+        close: () => setOpen(false, false),
+        toggle: () => setOpen(!isOpen, false),
+        dispose: () => {
+            unsubscribe();
+            clearTimeout(copyTimer);
+            host.remove();
+        },
+    };
+}
+function segmented(name, label, options, onChange) {
+    const fieldset = document.createElement("fieldset");
+    const legend = document.createElement("legend");
+    legend.textContent = label;
+    const group = document.createElement("div");
+    group.className = "segmented";
+    const inputs = options.map((option) => {
+        const wrapper = document.createElement("label");
+        const input = document.createElement("input");
+        input.type = "radio";
+        input.name = name;
+        input.value = option;
+        input.addEventListener("change", () => {
+            if (input.checked)
+                onChange(option);
+        });
+        const text = document.createElement("span");
+        text.textContent = option;
+        wrapper.append(input, text);
+        group.append(wrapper);
+        return input;
+    });
+    fieldset.append(legend, group);
+    return {
+        node: fieldset,
+        set: (value) => {
+            for (const input of inputs)
+                input.checked = input.value === value;
+        },
+    };
+}
+function select(id, label, options, onChange) {
+    const wrapper = document.createElement("div");
+    const caption = document.createElement("label");
+    caption.className = "label";
+    caption.htmlFor = id;
+    caption.textContent = label;
+    const box = document.createElement("div");
+    box.className = "select";
+    const control = document.createElement("select");
+    control.id = id;
+    for (const option of options) {
+        const item = document.createElement("option");
+        item.value = option;
+        item.textContent = option;
+        control.add(item);
+    }
+    control.addEventListener("change", () => onChange(control.value));
+    box.append(control, svgIcon(ICONS.chevron));
+    wrapper.append(caption, box);
+    return {
+        node: wrapper,
+        set: (value) => {
+            if (control.value !== value)
+                control.value = value;
+        },
+    };
+}

package/dist/production.d.ts

@@ -0,0 +1,3 @@
+/** Production entry point. Deliberately inert and free of DOM side effects. */
+export declare function mountDevAssistant(...args: readonly unknown[]): null;
+//# sourceMappingURL=production.d.ts.map

package/dist/production.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production.d.ts","sourceRoot":"","sources":["../src/production.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAGnE"}

package/dist/production.js

@@ -0,0 +1,5 @@
+/** Production entry point. Deliberately inert and free of DOM side effects. */
+export function mountDevAssistant(...args) {
+    void args;
+    return null;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@polymorfa/devtools",
+  "version": "0.1.0-dev.20260922094209",
+  "description": "Production-gated configuration, theming, and diagnostics assistant for Polymorfa UI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polymorfa/sdks.git",
+    "directory": "packages/devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/polymorfa/sdks/issues"
+  },
+  "homepage": "https://github.com/polymorfa/sdks#readme",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./production": {
+      "types": "./dist/production.d.ts",
+      "import": "./dist/production.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@polymorfa/ui": "0.1.0-dev.20260922094209"
+  },
+  "peerDependencies": {
+    "@polymorfa/browser": "0.1.0-dev.20260922094209"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}