carboncanvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Roitch
+
+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,160 @@
+# carboncanvas
+
+> **Carbon Canvas** — the free, open (**MIT**) client for the Carbon Canvas
+> review platform. `0.1.0`. The canvas + Inspector need no account and no
+> backend; team comments/realtime are an optional hosted add-on.
+
+A **Reviewable Flow Canvas** for React: a pan/zoom spatial canvas you author in
+JSX (`<DesignCanvas>` / `<DCSection>` / `<DCArtboard>` / `<DCPage>`), with a
+click-to-inspect **Inspector** that reads real React fibers, and a
+design-system **adapter seam** so token reverse-lookup + library detection work
+with any (or no) design system.
+
+The canvas + Inspector are fully client-side — no account, no backend. Add
+in-place **comments** (with live cursors/presence) by pointing the `comments`
+prop at a hosted Carbon Canvas backend (see [Comments](#comments) below); the
+comments/realtime runtime — including `socket.io-client` — is code-split into a
+lazy chunk, so it costs nothing until you enable it and pulls in no extra dep.
+
+## Install
+
+```sh
+npm i carboncanvas
+# react + react-dom are PEER deps — they use your app's existing copy
+```
+
+## Use
+
+```tsx
+import { DesignCanvas, DCSection, DCArtboard } from 'carboncanvas';
+
+export function Review() {
+  return (
+    <DesignCanvas inspector>
+      <DCSection title="Checkout flow">
+        <DCArtboard label="Cart" width={390} height={844}>
+          <YourCartScreen />
+        </DCArtboard>
+        <DCArtboard label="Payment" width={390} height={844}>
+          <YourPaymentScreen state="connecting" />
+        </DCArtboard>
+      </DCSection>
+    </DesignCanvas>
+  );
+}
+```
+
+> **One `<DesignCanvas>` per page.** The canvas chrome locates the active
+> viewport through a global `[data-dc-viewport]` lookup, so two sibling
+> DesignCanvas instances on one page cross-wire. Render at most one per route.
+> (Nested canvases inside an artboard are fine — they're scoped by nearest
+> viewport.)
+
+## Consumer build requirements
+
+Two build settings make the Inspector and durable comment pins work well. Both
+live in **your** app's build, not in this package:
+
+1. **`esbuild: { keepNames: true }`** — **required for readable inspection.** The
+   Inspector reads React component display names off the fiber tree; without
+   `keepNames`, minification renames them and the Hierarchy tree shows garbage.
+
+   Vite example:
+
+   ```ts
+   // vite.config.ts
+   export default defineConfig({
+     esbuild: { keepNames: true },
+   });
+   ```
+
+2. **The `data-anchor` Babel plugin (optional, recommended for comments)** —
+   stamps every host element with a deterministic `data-anchor="file:line:col"`
+   so comment pins survive edits/HMR. Shipped as a subpath export:
+
+   ```ts
+   // vite.config.ts
+   import react from '@vitejs/plugin-react';
+   import dataAnchor from 'carboncanvas/babel-plugin-data-anchor';
+
+   export default defineConfig({
+     plugins: [react({ babel: { plugins: [dataAnchor] } })],
+     esbuild: { keepNames: true },
+   });
+   ```
+
+   On **React 19** this plugin is what makes the Inspector's Source row work at
+   all — React 19 removed `fiber._debugSource`, so the source path comes entirely
+   from `data-anchor`. Wire it if you want the Source row on React 19.
+
+### Shortcut: `carbonPreset` (`carboncanvas/vite`)
+
+So you don't hand-copy `keepNames`, the package ships a Vite config fragment.
+Spread it into your config, and (optionally) pass the re-exported plugin to your
+`react()`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { carbonPreset, dataAnchorBabelPlugin } from 'carboncanvas/vite';
+
+export default defineConfig({
+  ...carbonPreset(),                       // sets esbuild.keepNames
+  plugins: [react({ babel: { plugins: [dataAnchorBabelPlugin] } })],
+});
+```
+
+The fragment only sets `keepNames` (a config fragment can't reach into your
+`react()` plugin's babel option), so the `data-anchor` plugin is a separate
+re-export you wire yourself. `carboncanvas publish` verifies the built bundle
+actually kept names and warns if it didn't.
+
+## Design-system adapter
+
+The Inspector resolves design tokens + detects library components through one
+swappable adapter. The default (`genericAdapter`) needs no design system and
+reports raw computed values. Install a custom adapter once at app start:
+
+```tsx
+import { setDesignSystemAdapter } from 'carboncanvas';
+import { myAdapter } from './myAdapter'; // implements DesignSystemAdapter
+
+setDesignSystemAdapter(myAdapter);
+```
+
+## Comments
+
+In-place, pin-anchored comments (with live cursors + presence) are an optional
+hosted add-on. Point the `comments` prop at your Carbon Canvas backend:
+
+```tsx
+<DesignCanvas
+  inspector
+  comments={{
+    canvasId: 'cnv_…',                     // the permanent comment partition (write-once)
+    serviceUrl: 'https://your-backend',    // the hosted comments/realtime backend
+    enableUrl: 'https://your-dashboard',   // where the "Enable / Renew" CTA points
+  }}
+>
+```
+
+No client-side key: entitlement resolves **server-side** from the registered
+canvas's owner account. For local development with no backend, use the in-memory
+mock instead: `comments={{ canvasId: 'demo', devMode: true }}`. The comments tab
+is always present — until the canvas is entitled it renders an upsell rather than
+a thread list. `socket.io-client` ships inside the lazy comments chunk, so it is
+**not** an additional install.
+
+## Exports
+
+- **Canvas:** `DesignCanvas`, `DCSection`, `DCArtboard`, `DCPage`, `DCPostIt`,
+  `useArtboardActive`
+- **Adapter seam:** `setDesignSystemAdapter`, `getDesignSystemAdapter`,
+  `genericAdapter`, and the `DesignSystemAdapter` type (+ `AdapterFiber`,
+  `ComponentKind`, `CssVarTokenSpec`, `TypographyTokenSpec`,
+  `UtilityClassPrefixes`, `AdapterTokens`)
+
+## Peer dependencies
+
+`react >=18` and `react-dom >=18` (externalized — your app's copy is reused).

package/brand-B9y8WrVi.js

@@ -0,0 +1,134 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function getAncestorScale(el) {
+  let scale = 1;
+  let cur = parentAcrossShadow(el);
+  while (cur) {
+    const t = window.getComputedStyle(cur).transform;
+    if (t && t !== "none") {
+      const m = new DOMMatrix(t);
+      if (m.a !== 0) scale *= m.a;
+    }
+    cur = parentAcrossShadow(cur);
+  }
+  return scale || 1;
+}
+__name(getAncestorScale, "getAncestorScale");
+function parentAcrossShadow(el) {
+  if (el.parentElement) return el.parentElement;
+  const root = el.getRootNode();
+  return root instanceof ShadowRoot ? root.host : null;
+}
+__name(parentAcrossShadow, "parentAcrossShadow");
+const FRAME_ATTR = "data-quilt-canvas-frame";
+const FRAME_OVERLAY_ATTR = "data-quilt-frame-overlay";
+function contentDocOf(frame) {
+  try {
+    const doc = frame.contentDocument;
+    return doc && doc.body ? doc : null;
+  } catch {
+    return null;
+  }
+}
+__name(contentDocOf, "contentDocOf");
+function frameForTarget(target) {
+  var _a;
+  if (target instanceof HTMLIFrameElement && target.hasAttribute(FRAME_ATTR)) return target;
+  if (!target.hasAttribute(FRAME_OVERLAY_ATTR)) return null;
+  const wrap = target.parentElement;
+  return (_a = wrap == null ? void 0 : wrap.querySelector(`iframe[${FRAME_ATTR}]`)) != null ? _a : null;
+}
+__name(frameForTarget, "frameForTarget");
+function isFrameEl(el) {
+  return enclosingFrameOf(el) !== null;
+}
+__name(isFrameEl, "isFrameEl");
+function enclosingFrameOf(el) {
+  try {
+    const win = el.ownerDocument.defaultView;
+    if (!win || win === window) return null;
+    const frame = win.frameElement;
+    return frame instanceof HTMLIFrameElement && frame.hasAttribute(FRAME_ATTR) ? frame : null;
+  } catch {
+    return null;
+  }
+}
+__name(enclosingFrameOf, "enclosingFrameOf");
+function frameBodyOf(el) {
+  return enclosingFrameOf(el) ? el.ownerDocument.body : null;
+}
+__name(frameBodyOf, "frameBodyOf");
+function frameScale(frame) {
+  const w = frame.clientWidth;
+  if (!w) return 1;
+  return frame.getBoundingClientRect().width / w || 1;
+}
+__name(frameScale, "frameScale");
+function descendIntoFrame(target, clientX, clientY) {
+  const frame = frameForTarget(target);
+  if (!frame) return null;
+  const doc = contentDocOf(frame);
+  if (!doc) return null;
+  const r = frame.getBoundingClientRect();
+  const s = frameScale(frame);
+  const inner = doc.elementFromPoint((clientX - r.left) / s, (clientY - r.top) / s);
+  return { el: inner != null ? inner : doc.body, frameBody: doc.body, frame };
+}
+__name(descendIntoFrame, "descendIntoFrame");
+function rectInHost(el) {
+  let rect = el.getBoundingClientRect();
+  let win = null;
+  try {
+    win = el.ownerDocument.defaultView;
+  } catch {
+    return rect;
+  }
+  let guard = 0;
+  while (win && win !== window && guard++ < 8) {
+    const frame = win.frameElement;
+    if (!(frame instanceof HTMLIFrameElement)) break;
+    const fr = frame.getBoundingClientRect();
+    const s = frameScale(frame);
+    rect = new DOMRect(
+      fr.left + rect.left * s,
+      fr.top + rect.top * s,
+      rect.width * s,
+      rect.height * s
+    );
+    win = frame.ownerDocument.defaultView;
+  }
+  return rect;
+}
+__name(rectInHost, "rectInHost");
+function closestAcrossFrames(el, selector) {
+  let cur = el;
+  let guard = 0;
+  while (cur && guard++ < 16) {
+    const hit = cur.closest(selector);
+    if (hit) return hit;
+    cur = enclosingFrameOf(cur);
+  }
+  return null;
+}
+__name(closestAcrossFrames, "closestAcrossFrames");
+const BRAND_NAME = "Carbon Canvas";
+const BRAND = {
+  name: BRAND_NAME,
+  // Maturity tag shown next to the name (kept from the origin "alpha" pill).
+  tag: "alpha",
+  tagTitle: "Alpha — APIs and tree behaviour may change without notice",
+  credit: "created by Alex Roitch"
+};
+export {
+  BRAND as B,
+  FRAME_ATTR as F,
+  contentDocOf as a,
+  BRAND_NAME as b,
+  closestAcrossFrames as c,
+  descendIntoFrame as d,
+  frameBodyOf as f,
+  getAncestorScale as g,
+  isFrameEl as i,
+  rectInHost as r
+};
+//# sourceMappingURL=brand-B9y8WrVi.js.map

package/brand-B9y8WrVi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-B9y8WrVi.js","sources":["../src/DesignCanvas/getAncestorScale.ts","../src/DesignCanvas/frameInspect.ts","../src/brand.ts"],"sourcesContent":["// Walks up the parent chain from `el` and multiplies any CSS `transform`\n// scale factors. Used by Inspector / XRay / ExplodedView to compensate for\n// the DesignCanvas viewport's `transform: scale(N)` — without this, an\n// element's getBoundingClientRect comes back at *visual* size (post-canvas-\n// zoom) while its computed paddings / font-sizes stay at natural CSS px,\n// and clones look like they were \"drag-resized\" rather than scaled.\n//\n// Assumes uniform scaling (a === d in the matrix), which is true for the\n// canvas. Returns 1 if no transforming ancestor exists.\n//\n// Crosses shadow boundaries (parentElement → host hop): frozen snapshot tiles\n// (src/viewer/FrozenTile) render inside a shadow root, but the canvas zoom\n// transform lives on a light-DOM ancestor of the host — without the hop, every\n// measurement inside a snapshot would ignore the canvas zoom. Light-DOM\n// callers are unaffected (a Document root node ends the walk exactly like the\n// old `parentElement === null` did).\nexport function getAncestorScale(el: Element): number {\n  let scale = 1;\n  let cur: Element | null = parentAcrossShadow(el);\n  while (cur) {\n    const t = window.getComputedStyle(cur).transform;\n    if (t && t !== 'none') {\n      const m = new DOMMatrix(t);\n      if (m.a !== 0) scale *= m.a;\n    }\n    cur = parentAcrossShadow(cur);\n  }\n  return scale || 1;\n}\n\nfunction parentAcrossShadow(el: Element): Element | null {\n  if (el.parentElement) return el.parentElement;\n  const root = el.getRootNode();\n  return root instanceof ShadowRoot ? root.host : null;\n}\n","// frameInspect — same-origin iframe plumbing for the IN-APP canvas mode\n// (the 2026-06-12 pivot: the user's live routes ARE the artboards, rendered\n// as same-origin iframes of their own running app).\n//\n// This is the iframe sibling of domInspect.ts's shadow-root plumbing, and the\n// two solve the same problem with the same shape: document-level listeners in\n// the HOST page never see events from inside an iframe, so comment/dev modes\n// cover each live frame with a transparent overlay (stamped\n// `data-quilt-frame-overlay`); a click/hover lands on the overlay in HOST\n// coordinates and we \"descend\" — point-map into the frame's content document\n// and resolve the real element under the cursor. Because the frames are the\n// customer's OWN app on their OWN origin, contentDocument is reachable and the\n// elements carry real React fibers — that's what makes the in-app Inspector\n// \"native fiber\" instead of DOM-mode.\n//\n// Coordinate model: inside a frame, rects are natural CSS px (the canvas zoom\n// transform scales the iframe ELEMENT in the host, never the layout inside).\n// `rectInHost` maps an inner rect out to host-viewport px through the frame\n// chain; `descendIntoFrame` maps a host point in. Everything that DRAWS in the\n// host (hover/selection outlines, pins) maps out; everything that MEASURES\n// (computed styles, box model) reads natural px straight off the inner element\n// — which is exactly what the Inspector wants to display.\n//\n// Library-core rules: framework-free, no design-system imports.\n\n/** Stamped on every live route iframe the in-app canvas renders. */\nexport const FRAME_ATTR = 'data-quilt-canvas-frame';\n\n/** Stamped on the transparent event-catching overlay above a live frame\n *  (present in comment/dev modes; absent while the tile is being interacted\n *  with in cursor mode). */\nexport const FRAME_OVERLAY_ATTR = 'data-quilt-frame-overlay';\n\n/** The frame's content document, or null when unreachable (cross-origin,\n *  detached, still loading about:blank with no body yet). */\nexport function contentDocOf(frame: HTMLIFrameElement): Document | null {\n  try {\n    const doc = frame.contentDocument;\n    return doc && doc.body ? doc : null;\n  } catch {\n    return null; // cross-origin — not a quilt canvas frame's normal state\n  }\n}\n\n/** The quilt canvas frame an overlay (or the frame itself) fronts, or null. */\nexport function frameForTarget(target: Element): HTMLIFrameElement | null {\n  if (target instanceof HTMLIFrameElement && target.hasAttribute(FRAME_ATTR)) return target;\n  if (!target.hasAttribute(FRAME_OVERLAY_ATTR)) return null;\n  // The overlay is absolutely positioned over the frame inside the same tile\n  // wrapper — find the frame among the wrapper's descendants.\n  const wrap = target.parentElement;\n  return wrap?.querySelector<HTMLIFrameElement>(`iframe[${FRAME_ATTR}]`) ?? null;\n}\n\n/** Is this element inside a quilt canvas frame's document (any nesting level)? */\nexport function isFrameEl(el: Element): boolean {\n  return enclosingFrameOf(el) !== null;\n}\n\n/** The quilt canvas frame ELEMENT (in the parent document) whose document\n *  contains `el`, or null for host-document elements. */\nexport function enclosingFrameOf(el: Element): HTMLIFrameElement | null {\n  try {\n    const win = el.ownerDocument.defaultView;\n    if (!win || win === window) return null;\n    const frame = win.frameElement;\n    return frame instanceof HTMLIFrameElement && frame.hasAttribute(FRAME_ATTR) ? frame : null;\n  } catch {\n    return null;\n  }\n}\n\n/** The frame document's body for an element inside a quilt canvas frame —\n *  the selector scope pins are built against (the iframe twin of\n *  domInspect's snapshotBodyOf). Null for host elements. */\nexport function frameBodyOf(el: Element): Element | null {\n  return enclosingFrameOf(el) ? el.ownerDocument.body : null;\n}\n\n/** Rendered scale of the frame's content on the host screen — the canvas zoom\n *  as it applies to this frame element. 1 when unscaled/unmeasurable. */\nexport function frameScale(frame: HTMLIFrameElement): number {\n  const w = frame.clientWidth;\n  if (!w) return 1;\n  return frame.getBoundingClientRect().width / w || 1;\n}\n\n/**\n * Descend through a frame overlay (or the frame element itself) into the live\n * document inside: map the HOST-viewport point to frame-content coordinates\n * and resolve the element under it. Returns the inner element plus the frame\n * body (the pin selector scope) and the frame, or null when `target` doesn't\n * front a readable quilt canvas frame — light-DOM paths stay untouched, same\n * contract as the snapshot descent.\n */\nexport function descendIntoFrame(\n  target: Element,\n  clientX: number,\n  clientY: number,\n): { el: Element; frameBody: Element; frame: HTMLIFrameElement } | null {\n  const frame = frameForTarget(target);\n  if (!frame) return null;\n  const doc = contentDocOf(frame);\n  if (!doc) return null;\n  const r = frame.getBoundingClientRect();\n  const s = frameScale(frame);\n  const inner = doc.elementFromPoint((clientX - r.left) / s, (clientY - r.top) / s);\n  return { el: inner ?? doc.body, frameBody: doc.body, frame };\n}\n\n/**\n * An element's bounding rect in HOST-viewport coordinates. Identity for host\n * elements; for elements inside (possibly nested) quilt canvas frames, maps\n * each frame's content coords out through the frame element's host rect and\n * rendered scale. Inner-document scroll is already baked into the inner\n * getBoundingClientRect, so no scroll math is needed here.\n */\nexport function rectInHost(el: Element): DOMRect {\n  let rect = el.getBoundingClientRect();\n  let win: Window | null = null;\n  try {\n    win = el.ownerDocument.defaultView;\n  } catch {\n    return rect;\n  }\n  let guard = 0;\n  while (win && win !== window && guard++ < 8) {\n    const frame = win.frameElement;\n    if (!(frame instanceof HTMLIFrameElement)) break;\n    const fr = frame.getBoundingClientRect();\n    const s = frameScale(frame);\n    rect = new DOMRect(\n      fr.left + rect.left * s,\n      fr.top + rect.top * s,\n      rect.width * s,\n      rect.height * s,\n    );\n    win = frame.ownerDocument.defaultView;\n  }\n  return rect;\n}\n\n/** `closest()` that keeps walking up through quilt canvas frame boundaries\n *  (frame-element hops) — the iframe twin of domInspect's closestAcrossShadow.\n *  Lets frame-content elements find their `[data-dc-slot]` artboard. */\nexport function closestAcrossFrames(el: Element, selector: string): Element | null {\n  let cur: Element | null = el;\n  let guard = 0;\n  while (cur && guard++ < 16) {\n    const hit = cur.closest(selector);\n    if (hit) return hit;\n    cur = enclosingFrameOf(cur);\n  }\n  return null;\n}\n\n/** Resolve `selector` inside every readable quilt canvas frame under `scope`\n *  (light-DOM querySelector can't cross the document boundary). First match\n *  wins — mirrors domInspect's querySnapshots. */\nexport function queryFrames(scope: ParentNode, selector: string): Element | null {\n  for (const frame of Array.from(\n    scope.querySelectorAll<HTMLIFrameElement>(`iframe[${FRAME_ATTR}]`),\n  )) {\n    const doc = contentDocOf(frame);\n    const el = doc?.body.querySelector(selector);\n    if (el) return el;\n  }\n  return null;\n}\n","// Single source of truth for the product name. The repo's working codename is\n// \"quilt\"; the public brand is \"Carbon Canvas\" (carboncanvas.design). The rename\n// is a one-line change here, not a find-and-replace across the inspector chrome —\n// the internal codename \"quilt\" stays in dir names and other identifiers.\nexport const BRAND_NAME = 'Carbon Canvas';\n\n// Header chrome shown in the Inspector panel. Tagline/credit live alongside the\n// name so the whole brand surface is editable in one place.\nexport const BRAND = {\n  name: BRAND_NAME,\n  // Maturity tag shown next to the name (kept from the origin \"alpha\" pill).\n  tag: 'alpha',\n  tagTitle: 'Alpha — APIs and tree behaviour may change without notice',\n  credit: 'created by Alex Roitch',\n} as const;\n"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -0,0 +1,271 @@
+import { CSSProperties } from 'react';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+
+export declare type AdapterFiber = {
+    return: AdapterFiber | null;
+    child: AdapterFiber | null;
+    sibling: AdapterFiber | null;
+    type: any;
+    memoizedProps: Record<string, any> | null;
+    stateNode: any;
+    [k: string]: any;
+};
+
+export declare type AdapterTokens = {
+    color: CssVarTokenSpec;
+    shadow: CssVarTokenSpec;
+    spacing: CssVarTokenSpec;
+    radius: CssVarTokenSpec;
+    typography: TypographyTokenSpec;
+    utilityClassPrefixes: UtilityClassPrefixes;
+};
+
+/**
+ * Pluggable authentication strategy for the network client. The default
+ * (`accountlessAuthProvider`) is account-less: a sign-in is just a name (and an
+ * optional email) — no password, no external identity provider, no verification.
+ * Swap in your own provider to integrate OAuth / SSO / a real account system.
+ */
+export declare interface AuthProvider {
+    /** Resolve the current user for a stored bearer token (null = signed out). */
+    me(token: string | null): Promise<Me | null>;
+    /** Establish a session from the given identity; returns the bearer token + user. */
+    signIn(input: {
+        name: string;
+        email?: string;
+    }): Promise<{
+        token: string;
+        me: Me;
+    }>;
+    /** Best-effort server-side session teardown for the given token. */
+    signOut?(token: string): Promise<void>;
+}
+
+/**
+ * The canvas interaction mode. One bar, mutually-exclusive modes:
+ *   • cursor  — normal pointer; play with the live prototypes, pan/zoom freely
+ *   • comment — drop pins + open the comments sidebar
+ *   • dev     — click-to-inspect + the inspector panel
+ *
+ * Owned by DesignCanvas and threaded into the Inspector / CommentLayer so each
+ * derives its `enabled` state from the shared mode rather than its own toggle.
+ */
+export declare type CanvasMode = 'cursor' | 'comment' | 'dev';
+
+/** Public `comments` prop on DesignCanvas. */
+export declare interface CommentsConfig {
+    canvasId: string;
+    /** The hosted comments service base URL (required for network mode). */
+    serviceUrl?: string;
+    /** Use the in-memory mock store instead of the network. */
+    devMode?: boolean;
+    /** Authentication strategy. Defaults to `accountlessAuthProvider` (name-only sign-in). */
+    auth?: AuthProvider;
+    /**
+     * Multiplayer presence: live cursors + the who's-here facepile (network mode
+     * only; needs the realtime socket). Default true — set false to run
+     * comments-only with no socket connection.
+     */
+    presence?: boolean;
+    /** Directory backend for @mention typeahead. Defaults to the service's `/api/directory`. */
+    directory?: DirectoryProvider;
+    /**
+     * Hostnames matching any of these patterns are treated as NON-stable (e.g.
+     * rotating preview/dev hosts) and fall back to the explicit per-project
+     * canvasId instead of auto-scoping by hostname. Default `[]` → every host is
+     * its own canvas.
+     */
+    unstableHostPatterns?: RegExp[];
+    /**
+     * Auto-provision hint sent on the first write to an unregistered canvas, so the
+     * service can resolve the canvas owner deterministically rather than from
+     * whoever comments first. Ignored once the canvas exists.
+     */
+    provisionHint?: string;
+    /**
+     * Where the comments upsell's "Enable / Renew" CTA points — your dashboard or
+     * checkout URL (Workstream B). Shown when the canvas owner isn't entitled
+     * (the always-visible comments tab renders the upsell instead of the live
+     * runtime). Optional; a missing/placeholder value renders a non-navigating CTA.
+     */
+    enableUrl?: string;
+}
+
+export declare type ComponentKind = 'library' | 'user';
+
+export declare type CssVarTokenSpec = {
+    cssVarPrefix: string;
+    display?: (suffix: string) => string;
+    preferOnCollision?: (existing: string, candidate: string, suffix: string) => boolean;
+};
+
+export declare function DCArtboard(_props: DCArtboardProps): ReactElement | null;
+
+export declare interface DCArtboardProps {
+    id?: string;
+    label: string;
+    width?: number;
+    height?: number;
+    style?: CSSProperties;
+    /**
+     * Make the artboard card a containing block for `position:fixed` descendants
+     * (adds `contain:layout`), so a host app's fixed portals — modals, drawer
+     * sheets, menus — clip to the tile instead of escaping to the transformed
+     * canvas. Used by composed live artboards (wave 10). Off by default.
+     */
+    contain?: boolean;
+    children?: ReactNode;
+}
+
+export declare function DCPage(_props: DCPageProps): ReactElement | null;
+
+export declare interface DCPageProps {
+    /** Stable page id; also the `?page=` deep-link value. Defaults to `title`. */
+    id?: string;
+    title: string;
+    children?: ReactNode;
+}
+
+export declare function DCPostIt({ children, top, left, right, bottom, rotate, width }: DCPostItProps): ReactElement;
+
+export declare interface DCPostItProps {
+    children?: ReactNode;
+    top?: number | string;
+    left?: number | string;
+    right?: number | string;
+    bottom?: number | string;
+    rotate?: number;
+    width?: number;
+}
+
+export declare function DCSection({ id, title, subtitle, children, gap }: DCSectionProps): ReactElement;
+
+export declare interface DCSectionProps {
+    id?: string;
+    title: string;
+    subtitle?: string;
+    children?: ReactNode;
+    gap?: number;
+}
+
+export declare function DesignCanvas({ children, minScale, maxScale, minActiveScale, style, inspector, comments, adapter, }: DesignCanvasProps): ReactElement;
+
+/**
+ * Props for {@link DesignCanvas}.
+ *
+ * @remarks
+ * **One `<DesignCanvas>` per page.** The canvas chrome (Inspector, ModeBar zoom,
+ * comment pin/cursor panning) locates the active viewport via a global
+ * `document.querySelector('[data-dc-viewport]')`, so two DesignCanvas instances
+ * mounted on the same page cross-wire. Render at most one per route; nested
+ * canvases-inside-an-artboard are supported (scoped by nearest-viewport), but two
+ * sibling canvases are not.
+ */
+export declare interface DesignCanvasProps {
+    children?: ReactNode;
+    minScale?: number;
+    maxScale?: number;
+    /**
+     * Artboards report `active = false` via `useArtboardActive()` when the
+     * viewport scale drops below this threshold (or when the artboard scrolls
+     * out of view). Heavy content (videos, canvases) should gate on it.
+     * Defaults to 0.35.
+     */
+    minActiveScale?: number;
+    style?: CSSProperties;
+    /** Enables the click-to-inspect overlay (library component + props + className). */
+    inspector?: boolean;
+    /**
+     * Connect a design system to the Inspector (token reverse-lookup, library
+     * component + icon detection). Defaults to the no-design-system generic
+     * adapter. See `../adapters` + `examples/springAdapter.ts`.
+     */
+    adapter?: DesignSystemAdapter;
+    /**
+     * Enables the comment layer (drop pins on artboard elements, thread, resolve).
+     * Inert when omitted/false. `canvasId` namespaces the data in the
+     * comments-service; `devMode` uses an in-memory mock store instead of the network.
+     */
+    comments?: false | CommentsConfig;
+}
+
+export declare interface DesignSystemAdapter {
+    libraryLabel: string;
+    libraryShortLabel: string;
+    isLibraryComponent(type: any): boolean;
+    componentName(type: any): string | null;
+    classify(type: any): {
+        kind: ComponentKind;
+        name: string | null;
+    };
+    findIconName(fiber: AdapterFiber | null): string | null;
+    iconWrapperSize?(fiber: AdapterFiber | null): string | null;
+    iconImportSnippet(name: string): string;
+    iconLabel: string;
+    tokens: AdapterTokens;
+    themeScopeAttr?: string;
+    themeForegroundToken?: string;
+}
+
+/** A person from the directory, for the @mention picker (GET /api/directory?q=). */
+export declare interface DirectoryPerson {
+    /** Stable directory id for the picked person (the service's user id). */
+    personId: string;
+    name: string;
+    /** Shown to disambiguate same-named people. */
+    email: string;
+    /**
+     * True when this person has already participated on the queried canvas (commented
+     * or been @mentioned). Server-set, only present when a `canvasId` is sent with the
+     * query; drives the "On this canvas" grouping in the picker. Undefined for the mock
+     * client and any query without a canvas → the picker shows a flat, ungrouped list.
+     */
+    isParticipant?: boolean;
+}
+
+/**
+ * Optional directory backend for the @mention typeahead. When omitted, the
+ * network client falls back to its own `/api/directory` endpoint.
+ */
+export declare interface DirectoryProvider {
+    search(q: string): Promise<DirectoryPerson[]>;
+}
+
+export declare const genericAdapter: DesignSystemAdapter;
+
+export declare function getDesignSystemAdapter(): DesignSystemAdapter;
+
+/** Signed-in profile (extends PublicUser with the write gate). */
+export declare interface Me extends PublicUser {
+    canWrite: boolean;
+}
+
+/** Curated public identity — what threads render. Never an email. */
+export declare interface PublicUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string | null;
+}
+
+export declare function setDesignSystemAdapter(adapter: DesignSystemAdapter): void;
+
+/** Point all DesignCanvas-family portals at `el` (null restores body). */
+export declare function setPortalRoot(el: HTMLElement | null): void;
+
+export declare type TypographyTokenSpec = {
+    classMatcher: (selectorText: string) => string[];
+    signature?: (s: CSSStyleDeclaration) => string;
+};
+
+export declare const useArtboardActive: () => boolean;
+
+export declare type UtilityClassPrefixes = {
+    typography: string;
+    text: string;
+    bg: string;
+    border: string;
+};
+
+export { }

package/index.js

@@ -0,0 +1,14 @@
+import { D, h, j, k, m, n, g, s, q, u } from "./lib-CSrTsI4Y.js";
+export {
+  D as DCArtboard,
+  h as DCPage,
+  j as DCPostIt,
+  k as DCSection,
+  m as DesignCanvas,
+  n as genericAdapter,
+  g as getDesignSystemAdapter,
+  s as setDesignSystemAdapter,
+  q as setPortalRoot,
+  u as useArtboardActive
+};
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}