@dreamlake/dockit 0.2.29 → 0.2.31

package/dist/components/CodeBlock.js

@@ -2,6 +2,8 @@ import { jsxs, Fragment, jsx } from "react/jsx-runtime";
 import { useContext, useRef, useState } from "react";
 import { CodeTabsContext } from "./code-tabs-context.js";
 import { useLineNumbers } from "../lib/use-line-numbers.js";
+import { copyWithGlyphBurst } from "../lib/glyph-burst.js";
+const BURST = { color: "var(--color-doc-template-ink)" };
 const headerBtnStyle = (active) => ({
   display: "inline-flex",
   alignItems: "center",
@@ -25,17 +27,14 @@ function CodeBlock({ children, filename, lang }) {
   const [copied, setCopied] = useState(false);
   const [wrap, setWrap] = useState(false);
   const [showLines, setShowLines] = useLineNumbers();
-  function copy() {
+  function copy(button) {
     const el = wrapRef.current?.querySelector("pre code");
     if (!el) return;
-    navigator.clipboard.writeText(el.innerText).then(
-      () => {
-        setCopied(true);
-        setTimeout(() => setCopied(false), 1400);
-      },
-      () => {
-      }
-    );
+    void copyWithGlyphBurst(button, el.innerText, BURST).then((ok) => {
+      if (!ok) return;
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1400);
+    });
   }
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     embedded && (filename || lang) && /* @__PURE__ */ jsx("span", { className: "dockit-code-tabs-label", title: filename || lang, children: filename || lang }),
@@ -115,7 +114,7 @@ function CodeBlock({ children, filename, lang }) {
                           children: "Wrap"
                         }
                       ),
-                      /* @__PURE__ */ jsx("button", { type: "button", onClick: copy, style: headerBtnStyle(copied), children: copied ? "Copied" : "Copy" })
+                      /* @__PURE__ */ jsx("button", { type: "button", onClick: (e) => copy(e.currentTarget), style: headerBtnStyle(copied), children: copied ? "Copied" : "Copy" })
                     ]
                   }
                 )
@@ -181,7 +180,7 @@ function CodeBlock({ children, filename, lang }) {
                     children: "Wrap"
                   }
                 ),
-                /* @__PURE__ */ jsx("button", { type: "button", onClick: copy, style: headerBtnStyle(copied), children: copied ? "Copied" : "Copy" })
+                /* @__PURE__ */ jsx("button", { type: "button", onClick: (e) => copy(e.currentTarget), style: headerBtnStyle(copied), children: copied ? "Copied" : "Copy" })
               ]
             }
           ),

package/dist/components/CodeTabs.d.ts

@@ -8,6 +8,13 @@ export declare function CodeExample({ children }: CodeExampleProps): import("rea
 export interface CodeTabsProps {
     children: ReactNode;
     'aria-label'?: string;
+    /**
+     * Opt-in sync group. Every CodeTabs with the same `syncKey` shows the same
+     * tab label, on this page and others; the choice persists in localStorage
+     * (`doc:code-tabs:<syncKey>`) and follows other browser tabs. A group that
+     * lacks the chosen label keeps its own selection.
+     */
+    syncKey?: string;
 }
 /** UIKit owns the frame and keyboard navigation; Dockit owns fenced examples. */
-export declare function CodeTabs({ children, 'aria-label': label }: CodeTabsProps): import("react").JSX.Element | null;
+export declare function CodeTabs({ children, syncKey, 'aria-label': label }: CodeTabsProps): import("react").JSX.Element | null;

package/dist/components/CodeTabs.js

@@ -1,23 +1,35 @@
 import { jsx, Fragment } from "react/jsx-runtime";
-import { Children, isValidElement } from "react";
+import { Children, isValidElement, useState } from "react";
 import { TabbedContainer } from "../vendor/@dreamlake/uikit/src/components/TabbedContainer/TabbedContainer.js";
 import { CodeTabsContext } from "./code-tabs-context.js";
+import { useCodeTabsChoice, resolveCodeTab } from "../lib/code-tabs-sync.js";
 function CodeExample({ children }) {
   return /* @__PURE__ */ jsx(Fragment, { children });
 }
-function CodeTabs({ children, "aria-label": label = "Code examples" }) {
+function CodeTabs({ children, syncKey, "aria-label": label = "Code examples" }) {
   const examples = Children.toArray(children).filter(isValidElement);
-  if (!examples.length) return null;
-  return /* @__PURE__ */ jsx("div", { "data-code-tabs": true, children: /* @__PURE__ */ jsx(CodeTabsContext.Provider, { value: true, children: /* @__PURE__ */ jsx(
+  const items = examples.map((example, index) => ({
+    value: String(example.key ?? index),
+    label: example.props.label,
+    children: example.props.children
+  }));
+  const [choice, choose] = useCodeTabsChoice(syncKey);
+  const [own, setOwn] = useState(void 0);
+  const value = resolveCodeTab(items, choice, own);
+  if (value !== own && choice !== null && value !== void 0) setOwn(value);
+  if (!items.length) return null;
+  return /* @__PURE__ */ jsx("div", { "data-code-tabs": true, "data-code-tabs-sync": syncKey, children: /* @__PURE__ */ jsx(CodeTabsContext.Provider, { value: true, children: /* @__PURE__ */ jsx(
     TabbedContainer,
     {
       "aria-label": label,
       className: "dockit-code-tabs",
-      items: examples.map((example, index) => ({
-        value: String(example.key ?? index),
-        label: example.props.label,
-        children: example.props.children
-      }))
+      items,
+      value,
+      onValueChange: (next) => {
+        setOwn(next);
+        const picked = items.find((item) => item.value === next);
+        if (picked) choose(picked.label);
+      }
     }
   ) }) });
 }

package/dist/components/Preview.js

@@ -1,6 +1,7 @@
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
 import { useState, useEffect } from "react";
 import { useLineNumbers } from "../lib/use-line-numbers.js";
+import { copyWithGlyphBurst } from "../lib/glyph-burst.js";
 function langFromFilename(name) {
   if (!name) return "tsx";
   const ext = name.split(".").pop()?.toLowerCase();
@@ -175,15 +176,12 @@ function Preview({
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
   }, [fullscreen]);
-  function copy() {
-    navigator.clipboard.writeText(visibleSource).then(
-      () => {
-        setCopied(true);
-        setTimeout(() => setCopied(false), 1400);
-      },
-      () => {
-      }
-    );
+  function copy(button) {
+    void copyWithGlyphBurst(button, visibleSource, { color: "var(--color-doc-template-ink)" }).then((ok) => {
+      if (!ok) return;
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1400);
+    });
   }
   return /* @__PURE__ */ jsxs(
     "div",
@@ -264,7 +262,7 @@ function Preview({
                   "button",
                   {
                     type: "button",
-                    onClick: copy,
+                    onClick: (e) => copy(e.currentTarget),
                     "aria-label": "Copy source",
                     style: headerBtnStyle(copied),
                     children: copied ? "Copied" : "Copy"

package/dist/components/TOC.js

@@ -3,6 +3,7 @@ import { useState, useRef, useEffect, useMemo } from "react";
 import { usePageContext } from "vike-react/usePageContext";
 import { normalizePath, findPage } from "../lib/navigation.js";
 import { siteConfig } from "../site-config.js";
+import { useHiddenToggle } from "../lib/use-hidden-toggle.js";
 const TOC_KEY_PREFIX = "toc-collapsed:";
 const X0 = 4;
 const X_INDENT_H3 = 12;
@@ -52,19 +53,21 @@ function scrollToHeading(e, id) {
 function TOC() {
   const { urlPathname } = usePageContext();
   const currentPath = normalizePath(urlPathname);
+  const [showDeveloperLinks] = useHiddenToggle();
   const mdHref = (() => {
     const meta = findPage(urlPathname);
     if (!meta || meta.noindex) return null;
     return currentPath === "/" ? "/index.md" : `${currentPath}.md`;
   })();
   const editHref = (() => {
+    if (!showDeveloperLinks || !siteConfig.docsRepoUrl) return null;
     const meta = findPage(urlPathname);
     if (!meta) return null;
     const slug = currentPath === "/" ? "index" : currentPath.replace(/^\//, "");
     const pagesPath = siteConfig.docsPagesPath ?? "docs/pages";
-    return `${siteConfig.docsRepoUrl}/edit/${siteConfig.docsBranch}/${pagesPath}/${slug}/+Page.mdx`;
+    return `${siteConfig.docsRepoUrl}/edit/${encodeURIComponent(siteConfig.docsBranch)}/${pagesPath}/${slug}/+Page.mdx`;
   })();
-  const issueHref = `${siteConfig.docsRepoUrl}/issues/new`;
+  const issueHref = showDeveloperLinks && siteConfig.docsRepoUrl ? `${siteConfig.docsRepoUrl}/issues/new` : null;
   const [headings, setHeadings] = useState([]);
   const [endPos, setEndPos] = useState(null);
   const [pathD, setPathD] = useState("");
@@ -643,7 +646,7 @@ function TOC() {
                   children: "Edit this page"
                 }
               ),
-              /* @__PURE__ */ jsx(
+              issueHref && /* @__PURE__ */ jsx(
                 "a",
                 {
                   href: issueHref,

package/dist/components/Topbar.js

@@ -38,6 +38,7 @@ const SEARCH_INSET = `max(${SEARCH_GUTTER}px, calc((100vw - ${SEARCH_MAX_W}px) /
 function Topbar({ searchOpen, onOpenSearch, onCloseSearch, query, setQuery }) {
   const { urlPathname } = usePageContext();
   const current = findPage(urlPathname);
+  const [showDeveloperLinks] = useHiddenToggle();
   const hasTabs = TABS.length > 0;
   const activeTab = internalTabs().find((t) => t.id === tabForUrl(urlPathname));
   const versionChips = activeTab?.versionChips ?? siteConfig.versionChips ?? [];
@@ -353,7 +354,7 @@ function Topbar({ searchOpen, onOpenSearch, onCloseSearch, query, setQuery }) {
                 },
                 chip.label
               )),
-              siteConfig.gitHash && /* @__PURE__ */ jsxs(
+              showDeveloperLinks && siteConfig.gitHash && /* @__PURE__ */ jsxs(
                 "span",
                 {
                   className: "hidden md:inline-flex items-center text-doc-template-muted border border-doc-template-faint",
@@ -553,7 +554,7 @@ function Topbar({ searchOpen, onOpenSearch, onCloseSearch, query, setQuery }) {
             className: "flex items-stretch gap-2.5 md:gap-3.5 pr-[14px] md:pr-[22px]",
             style: { gridColumn: 3, gridRow: 1, justifySelf: "end", ...palFade(searchOpen) },
             children: /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-3.5", children: [
-              siteConfig.repoUrl && /* @__PURE__ */ jsx(
+              showDeveloperLinks && siteConfig.repoUrl && /* @__PURE__ */ jsx(
                 "a",
                 {
                   href: siteConfig.repoUrl,

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { useHiddenToggle } from './lib/use-hidden-toggle';
 export { useLineNumbers } from './lib/use-line-numbers';
 export { useLocalStorage, DOC_PREFIX, docKey } from './lib/use-local-storage';
 export { useMediaQuery } from './lib/use-media-query';
+export { glyphBurst, copyWithGlyphBurst, burstGlyphs, type GlyphBurstOptions } from './lib/glyph-burst';
 export { Callout } from './components/Callout';
 export { Chip, type ChipProps, type ChipVariant } from './components/Chip';
 export { ClientOnly } from './components/ClientOnly';

package/dist/index.js

@@ -11,6 +11,7 @@ import { useHiddenToggle } from "./lib/use-hidden-toggle.js";
 import { useLineNumbers } from "./lib/use-line-numbers.js";
 import { DOC_PREFIX, docKey, useLocalStorage } from "./lib/use-local-storage.js";
 import { useMediaQuery } from "./lib/use-media-query.js";
+import { burstGlyphs, copyWithGlyphBurst, glyphBurst } from "./lib/glyph-burst.js";
 import { Callout } from "./components/Callout.js";
 import { Chip } from "./components/Chip.js";
 import { ClientOnly } from "./components/ClientOnly.js";
@@ -66,11 +67,14 @@ export {
   ThemeToggle,
   Topbar,
   VersionBadge,
+  burstGlyphs,
+  copyWithGlyphBurst,
   defaultResults,
   defineSiteConfig,
   docKey,
   findPage,
   getAdjacentPages,
+  glyphBurst,
   groupedPages,
   groupedVisiblePages,
   initDocs,

package/dist/lib/code-tabs-sync.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opt-in sync groups for `<CodeTabs syncKey="…">` (Docusaurus `groupId`).
+ *
+ * Every CodeTabs sharing a `syncKey` shows the same tab *label*. The
+ * choice is persisted at `doc:code-tabs:<syncKey>` through the same
+ * `doc:` storage layer as `useLocalStorage`, so it survives navigation and
+ * reloads, follows other browser tabs via the native `storage` event, and
+ * follows other blocks on the page via the same-tab broadcast. An
+ * in-memory copy keeps in-page sync working when storage is blocked.
+ */
+export declare const codeTabsStorageKey: (syncKey: string) => string;
+/** Current choice for a group (client only). */
+export declare function readCodeTabsChoice(syncKey: string): string | null;
+/** Choose a label for every block in the group, here and in other tabs. */
+export declare function writeCodeTabsChoice(syncKey: string, label: string): void;
+/** Notify when the group's choice changes from any source. */
+export declare function subscribeCodeTabsChoice(syncKey: string, onChange: () => void): () => void;
+export interface CodeTabItem {
+    value: string;
+    label: string;
+}
+/**
+ * Which tab a block shows: the group's choice when the block has that label;
+ * otherwise the block keeps its own last selection, then its first tab.
+ */
+export declare function resolveCodeTab(items: readonly CodeTabItem[], choice: string | null, own: string | undefined): string | undefined;
+/**
+ * The group's chosen label, or `null` without a `syncKey`/choice.
+ *
+ * SSR and the hydration pass both see `null`, so markup always matches the
+ * server's (first-tab) HTML. A layout effect then re-renders before the
+ * browser paints the hydrated tree; client-side navigation reads the stored
+ * choice on first render, so no flash there.
+ */
+export declare function useCodeTabsChoice(syncKey: string | undefined): [string | null, (label: string) => void];

package/dist/lib/code-tabs-sync.js

@@ -0,0 +1,63 @@
+import { useCallback, useSyncExternalStore, useReducer, useLayoutEffect } from "react";
+import { subscribeDocStorage, readDocStorage, writeDocStorage } from "./use-local-storage.js";
+const codeTabsStorageKey = (syncKey) => `code-tabs:${syncKey}`;
+const memory = /* @__PURE__ */ new Map();
+const asLabel = (value) => typeof value === "string" ? value : null;
+function readCodeTabsChoice(syncKey) {
+  let choice = memory.get(syncKey);
+  if (choice === void 0) {
+    choice = asLabel(readDocStorage(codeTabsStorageKey(syncKey)));
+    memory.set(syncKey, choice);
+  }
+  return choice;
+}
+function writeCodeTabsChoice(syncKey, label) {
+  memory.set(syncKey, label);
+  writeDocStorage(codeTabsStorageKey(syncKey), label);
+}
+function subscribeCodeTabsChoice(syncKey, onChange) {
+  return subscribeDocStorage(codeTabsStorageKey(syncKey), (change) => {
+    if (change) memory.set(syncKey, asLabel(change.value));
+    else memory.delete(syncKey);
+    onChange();
+  });
+}
+function resolveCodeTab(items, choice, own) {
+  const chosen = choice === null ? void 0 : items.find((item) => item.label === choice);
+  if (chosen) return chosen.value;
+  return items.some((item) => item.value === own) ? own : items[0]?.value;
+}
+const noop = () => () => {
+};
+const serverSnapshot = () => null;
+function useCodeTabsChoice(syncKey) {
+  const subscribe = useCallback(
+    (onChange) => syncKey ? subscribeCodeTabsChoice(syncKey, onChange) : () => {
+    },
+    [syncKey]
+  );
+  const choice = useSyncExternalStore(
+    syncKey ? subscribe : noop,
+    () => syncKey ? readCodeTabsChoice(syncKey) : null,
+    serverSnapshot
+  );
+  const [, rerender] = useReducer((n) => n + 1, 0);
+  useLayoutEffect(() => {
+    if (syncKey && readCodeTabsChoice(syncKey) !== choice) rerender();
+  }, [syncKey]);
+  const choose = useCallback(
+    (label) => {
+      if (syncKey) writeCodeTabsChoice(syncKey, label);
+    },
+    [syncKey]
+  );
+  return [choice, choose];
+}
+export {
+  codeTabsStorageKey,
+  readCodeTabsChoice,
+  resolveCodeTab,
+  subscribeCodeTabsChoice,
+  useCodeTabsChoice,
+  writeCodeTabsChoice
+};

package/dist/lib/dev-metadata-plugin.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from 'vite';
+/** Encode shell metadata before bundling; never include original-source maps. */
+export declare function devMetadataPlugin(): Plugin;

package/dist/lib/dev-metadata-plugin.js

@@ -0,0 +1,81 @@
+import { transformWithEsbuild } from "vite";
+const fields = /* @__PURE__ */ new Set(["repoUrl", "docsRepoUrl", "docsBranch", "docsPagesPath", "gitHash"]);
+function staticString(node) {
+  if (node.type === "Literal" && typeof node.value === "string") return node.value;
+  if (node.type === "TemplateLiteral") {
+    const parts = node.quasis;
+    const expressions = node.expressions;
+    let value = parts[0].value.cooked;
+    for (let i = 0; i < expressions.length; i++) {
+      const part = staticString(expressions[i]);
+      if (part === null) return null;
+      value += part + parts[i + 1].value.cooked;
+    }
+    return value;
+  }
+  return null;
+}
+function devMetadataPlugin() {
+  let define = {};
+  return {
+    name: "dockit-dev-metadata",
+    enforce: "pre",
+    apply: "build",
+    configResolved(config) {
+      define = Object.fromEntries(Object.entries(config.define ?? {}).map(([key, value]) => [
+        key,
+        typeof value === "string" ? value : JSON.stringify(value)
+      ]));
+      if (config.build.sourcemap) {
+        throw new Error("Dockit developer metadata requires build.sourcemap: false");
+      }
+    },
+    async transform(source, id) {
+      if (!/(?:^|\/)site\.config\.[cm]?[jt]s$/.test(id)) return null;
+      const compiled = await transformWithEsbuild(source, id, {
+        loader: "ts",
+        target: "esnext",
+        define,
+        sourcemap: false,
+        legalComments: "none"
+      });
+      const edits = [];
+      const visit = (node) => {
+        if (node.type === "Property") {
+          const key = node.key;
+          const name = key.type === "Identifier" && !node.computed ? key.name : key.value;
+          if (typeof name === "string" && fields.has(name)) {
+            const value = node.value;
+            const text = staticString(value);
+            if (text === null) {
+              this.error(`Dockit ${name} must be a string literal or a build-time define in ${id}`);
+            }
+            const bytes = Array.from({ length: text.length }, (_, i) => text.charCodeAt(i) ^ 90);
+            edits.push({
+              start: value.start,
+              end: value.end,
+              text: `[${bytes.join(",")}].map(n=>String.fromCharCode(n^90)).join("")`
+            });
+            return;
+          }
+        }
+        for (const value of Object.values(node)) {
+          if (Array.isArray(value)) {
+            for (const item of value) if (item?.type) visit(item);
+          } else if (value && typeof value === "object" && "type" in value) {
+            visit(value);
+          }
+        }
+      };
+      visit(this.parse(compiled.code));
+      let code = compiled.code;
+      for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+      }
+      return { code, map: { mappings: "" } };
+    }
+  };
+}
+export {
+  devMetadataPlugin
+};

package/dist/lib/glyph-burst.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Glyph burst — the copy-button flourish. After a successful copy, a handful
+ * of the copied code's own punctuation (`{ } ( ) ; = …`) pops out of the
+ * button in its ink and mono face, arcs under gravity, and fades.
+ *
+ * Everything happens after the clipboard write resolves, inside one fixed,
+ * pointer-transparent overlay that removes itself; only transform and
+ * opacity animate, so nothing on the page reflows. Reduced motion, no
+ * matchMedia, or no Web Animations API → no burst, plain feedback only.
+ *
+ * Kept dependency-free on purpose; the DreamLake app ships a twin of this
+ * file (lib/notes/glyphBurst.ts) so both copy buttons feel the same.
+ */
+/** Up to `count` distinct symbols from `source`, padded with code punctuation. */
+export declare function burstGlyphs(source: string, count?: number): string[];
+export interface GlyphBurstOptions {
+    /** CSS font-family for the glyphs; defaults to the origin's computed font. */
+    font?: string;
+    /** CSS color for the glyphs; defaults to the origin's computed color. */
+    color?: string;
+}
+/** Fire-and-forget. Never throws; does nothing under reduced motion. */
+export declare function glyphBurst(origin: Element, source: string, options?: GlyphBurstOptions): void;
+/**
+ * Write `text` to the clipboard, then (only on success) burst from `origin`.
+ * Resolves true when the copy happened; the burst never delays or fails it.
+ */
+export declare function copyWithGlyphBurst(origin: Element, text: string, options?: GlyphBurstOptions): Promise<boolean>;

package/dist/lib/glyph-burst.js

@@ -0,0 +1,111 @@
+const FALLBACK = "{}();=<>/*[]#:";
+const SYMBOL = /[^\p{L}\p{N}\s_]/u;
+const COUNT = 10;
+function burstGlyphs(source, count = COUNT) {
+  const glyphs = [];
+  for (const ch of source) {
+    if (glyphs.length >= count) break;
+    if (SYMBOL.test(ch) && !glyphs.includes(ch)) glyphs.push(ch);
+  }
+  for (const ch of FALLBACK) {
+    if (glyphs.length >= count) break;
+    if (!glyphs.includes(ch)) glyphs.push(ch);
+  }
+  return glyphs;
+}
+function motionAllowed() {
+  if (typeof window === "undefined" || typeof document === "undefined")
+    return false;
+  if (typeof window.matchMedia !== "function") return false;
+  return !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function glyphBurst(origin, source, options = {}) {
+  try {
+    if (!motionAllowed()) return;
+    const rect = origin.getBoundingClientRect();
+    if (!rect.width && !rect.height) return;
+    const computed = window.getComputedStyle(origin);
+    const font = options.font ?? computed.fontFamily;
+    const color = options.color ?? computed.color;
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    const layer = document.createElement("div");
+    layer.setAttribute("aria-hidden", "true");
+    layer.setAttribute("data-glyph-burst", "");
+    Object.assign(layer.style, {
+      position: "fixed",
+      inset: "0",
+      pointerEvents: "none",
+      overflow: "hidden",
+      contain: "strict",
+      zIndex: "2147483647"
+    });
+    const glyphs = burstGlyphs(source);
+    const animations = [];
+    glyphs.forEach((glyph, i) => {
+      const span = document.createElement("span");
+      span.textContent = glyph;
+      Object.assign(span.style, {
+        position: "absolute",
+        left: `${x}px`,
+        top: `${y}px`,
+        font: `500 12px/1 ${font}`,
+        color,
+        whiteSpace: "pre",
+        willChange: "transform, opacity"
+      });
+      layer.append(span);
+      if (typeof span.animate !== "function") return;
+      const angle = (-150 + 120 * (i + 0.2 + Math.random() * 0.6) / glyphs.length) * Math.PI / 180;
+      const speed = 170 + Math.random() * 60;
+      const vx = Math.cos(angle) * speed * 0.6;
+      const vy = Math.sin(angle) * speed;
+      const gravity = 440;
+      const spin = (Math.random() - 0.5) * 300;
+      const frames = [];
+      for (let step = 0; step <= 8; step++) {
+        const t = step / 8;
+        const dx = vx * t;
+        const dy = vy * t + gravity * t * t / 2;
+        frames.push({
+          offset: t,
+          opacity: t < 0.6 ? 0.9 : 0.9 * (1 - (t - 0.6) / 0.4),
+          transform: `translate(-50%, -50%) translate(${dx.toFixed(1)}px, ${dy.toFixed(1)}px) rotate(${(spin * t).toFixed(1)}deg) scale(${t === 0 ? 0.5 : 1})`
+        });
+      }
+      animations.push(
+        span.animate(frames, {
+          duration: 760 + Math.random() * 220,
+          delay: i * 12,
+          easing: "cubic-bezier(.3,.55,.55,1)",
+          fill: "both"
+        })
+      );
+    });
+    if (!animations.length) return;
+    document.body.append(layer);
+    let removed = false;
+    const remove = () => {
+      if (removed) return;
+      removed = true;
+      layer.remove();
+    };
+    Promise.all(animations.map((a) => a.finished)).then(remove, remove);
+    setTimeout(remove, 1600);
+  } catch {
+  }
+}
+async function copyWithGlyphBurst(origin, text, options) {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    return false;
+  }
+  glyphBurst(origin, text, options);
+  return true;
+}
+export {
+  burstGlyphs,
+  copyWithGlyphBurst,
+  glyphBurst
+};

package/dist/lib/use-local-storage.d.ts

@@ -1,5 +1,19 @@
 export declare const DOC_PREFIX = "doc:";
 export declare const docKey: (k: string) => string;
+/** Read and JSON-decode a `doc:` key. Missing, malformed, or blocked
+ *  storage (privacy mode, sandboxed iframe, SSR) all return `undefined`. */
+export declare function readDocStorage<T>(key: string): T | undefined;
+/** JSON-encode a value into a `doc:` key and notify same-tab subscribers.
+ *  The broadcast fires even when persistence fails, so live in-page sync
+ *  survives disabled storage. */
+export declare function writeDocStorage<T>(key: string, value: T): void;
+/** Subscribe to changes of a `doc:` key from this tab (custom event) and
+ *  other tabs (native `storage` event; `key === null` means storage was
+ *  cleared). Same-tab writes pass `{ value }`, so subscribers stay in sync
+ *  even when storage is blocked; cross-tab changes pass `null` (re-read). */
+export declare function subscribeDocStorage(key: string, onChange: (sameTab: {
+    value: unknown;
+} | null) => void): () => void;
 /**
  * SSR-safe localStorage-backed state. Returns the in-memory React
  * value and a setter that mirrors the value into localStorage and

package/dist/lib/use-local-storage.js

@@ -2,50 +2,62 @@ import { useState, useRef, useEffect, useCallback } from "react";
 const DOC_PREFIX = "doc:";
 const docKey = (k) => k.startsWith(DOC_PREFIX) ? k : DOC_PREFIX + k;
 const SAME_TAB_EVENT = "doc:storage";
+function readDocStorage(key) {
+  if (typeof window === "undefined") return void 0;
+  const fullKey = docKey(key);
+  try {
+    const raw = localStorage.getItem(fullKey);
+    return raw === null ? void 0 : JSON.parse(raw);
+  } catch (err) {
+    return void 0;
+  }
+}
+function writeDocStorage(key, value) {
+  if (typeof window === "undefined") return;
+  const fullKey = docKey(key);
+  try {
+    localStorage.setItem(fullKey, JSON.stringify(value));
+  } catch {
+  }
+  window.dispatchEvent(
+    new CustomEvent(SAME_TAB_EVENT, { detail: { key: fullKey, value } })
+  );
+}
+function subscribeDocStorage(key, onChange) {
+  if (typeof window === "undefined") return () => {
+  };
+  const fullKey = docKey(key);
+  const onStorage = (e) => {
+    if (e.key === fullKey || e.key === null) onChange(null);
+  };
+  const onSameTab = (e) => {
+    const detail = e.detail;
+    if (detail?.key === fullKey) onChange({ value: detail.value });
+  };
+  window.addEventListener("storage", onStorage);
+  window.addEventListener(SAME_TAB_EVENT, onSameTab);
+  return () => {
+    window.removeEventListener("storage", onStorage);
+    window.removeEventListener(SAME_TAB_EVENT, onSameTab);
+  };
+}
 function useLocalStorage(key, defaultValue) {
   const fullKey = docKey(key);
   const [value, setValue] = useState(defaultValue);
   const defaultRef = useRef(defaultValue);
   defaultRef.current = defaultValue;
   useEffect(() => {
-    if (typeof window === "undefined") return;
     const read = () => {
-      try {
-        const raw = localStorage.getItem(fullKey);
-        if (raw === null) {
-          setValue(defaultRef.current);
-        } else {
-          setValue(JSON.parse(raw));
-        }
-      } catch (err) {
-      }
+      const stored = readDocStorage(fullKey);
+      setValue(stored === void 0 ? defaultRef.current : stored);
     };
     read();
-    const onStorage = (e) => {
-      if (e.key === fullKey) read();
-    };
-    const onSameTab = (e) => {
-      const detail = e.detail;
-      if (detail?.key === fullKey) read();
-    };
-    window.addEventListener("storage", onStorage);
-    window.addEventListener(SAME_TAB_EVENT, onSameTab);
-    return () => {
-      window.removeEventListener("storage", onStorage);
-      window.removeEventListener(SAME_TAB_EVENT, onSameTab);
-    };
+    return subscribeDocStorage(fullKey, () => read());
   }, [fullKey]);
   const set = useCallback(
     (next) => {
       setValue(next);
-      if (typeof window === "undefined") return;
-      try {
-        localStorage.setItem(fullKey, JSON.stringify(next));
-      } catch {
-      }
-      window.dispatchEvent(
-        new CustomEvent(SAME_TAB_EVENT, { detail: { key: fullKey } })
-      );
+      writeDocStorage(fullKey, next);
     },
     [fullKey]
   );
@@ -54,5 +66,8 @@ function useLocalStorage(key, defaultValue) {
 export {
   DOC_PREFIX,
   docKey,
-  useLocalStorage
+  readDocStorage,
+  subscribeDocStorage,
+  useLocalStorage,
+  writeDocStorage
 };

package/dist/vite.js

@@ -1,4 +1,5 @@
 import { mdxFrontmatterLoader } from "./lib/mdx-frontmatter-loader.js";
+import { devMetadataPlugin } from "./lib/dev-metadata-plugin.js";
 import { readFile } from "node:fs/promises";
 import react from "@vitejs/plugin-react";
 import vike from "vike/plugin";
@@ -30,6 +31,7 @@ function mdxRawLoader() {
 }
 function dockit() {
   return [
+    devMetadataPlugin(),
     tailwindcss(),
     mdxRawLoader(),
     mdxFrontmatterLoader(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamlake/dockit",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "The DreamLake documentation shell — Vike + React + Tailwind v4 + MDX docs framework with sidebar, TOC, search, and theming",
   "license": "MIT",
   "type": "module",