@nowline/embed 0.4.1 → 0.4.2

package/dist/share.d.ts

@@ -0,0 +1,46 @@
+/** Default share destination — the Nowline Free app's open route. */
+export declare const DEFAULT_SHARE_BASE = "https://free.nowline.io/open";
+/**
+ * The `share` initialize option selects where share links point.
+ *
+ * - `true` — use DEFAULT_SHARE_BASE (the default).
+ * - `string` — a base URL with optional path; built via the URL API so
+ *   `https://foo.com/open` → `https://foo.com/open#text=…`.
+ * - `false` / `'none'` — disable the share anchor entirely.
+ * - `{ textUrl, remoteUrl }` — escape hatch for non-hash URL shapes;
+ *   `{text}` substituted with the base64url payload, `{url}` with the
+ *   percent-encoded source URL.
+ */
+export type ShareOption = boolean | 'none' | string | {
+    textUrl: string;
+    remoteUrl: string;
+};
+/**
+ * Encode source text → `#text=<base64url(zlib(utf8(source)))>`.
+ *
+ * The return value includes the `#text=` key so callers can use it
+ * directly as a URL fragment.
+ *
+ * Sync, single code path, no feature-detect.
+ */
+export declare function encodeText(source: string): string;
+export interface BuildShareLinkOptions {
+    /** The roadmap source text (used to build the #text= fragment). */
+    source: string;
+    /**
+     * Resolved source URL for the block (per-block → global → undefined).
+     * Only `https:` URLs are emitted as `#url=`; anything else falls
+     * back to the inline `#text=` encoding.
+     */
+    sourceUrl?: string | undefined;
+    /** The `share` option from InitializeOptions. */
+    share: ShareOption;
+}
+/**
+ * Build the full "Share on Nowline" URL for a rendered block.
+ *
+ * Returns `null` when `share` is `false` or `'none'`, signalling that
+ * no anchor should be rendered.
+ */
+export declare function buildShareLink({ source, sourceUrl, share }: BuildShareLinkOptions): string | null;
+//# sourceMappingURL=share.d.ts.map

package/dist/share.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.d.ts","sourceRoot":"","sources":["../src/share.ts"],"names":[],"mappings":"AAeA,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAgBD,MAAM,WAAW,qBAAqB;IAClC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,iDAAiD;IACjD,KAAK,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAwBjG"}

package/dist/share.js

@@ -0,0 +1,76 @@
+// Share-link generation for the "Share on Nowline" anchor that the
+// auto-scan loop appends after each rendered SVG.
+//
+// Encoding grammar (normative — defined in specs/embed.md):
+//   #text=base64url(zlib(utf8(source)))
+//   #url=<https-url>
+//
+// zlib = RFC 1950 via fflate zlibSync (byte-compatible with native
+// CompressionStream('deflate')); base64url strips padding and maps
+// +→- /→_.
+//
+// Sync, works on every browser, no feature-detect.
+import { zlibSync } from 'fflate';
+/** Default share destination — the Nowline Free app's open route. */
+export const DEFAULT_SHARE_BASE = 'https://free.nowline.io/open';
+/**
+ * Encode source text → `#text=<base64url(zlib(utf8(source)))>`.
+ *
+ * The return value includes the `#text=` key so callers can use it
+ * directly as a URL fragment.
+ *
+ * Sync, single code path, no feature-detect.
+ */
+export function encodeText(source) {
+    return `#text=${_encodePayload(source)}`;
+}
+/** base64url(zlib(utf8(source))) without the `#text=` prefix. */
+function _encodePayload(source) {
+    const bytes = new TextEncoder().encode(source);
+    const compressed = zlibSync(bytes);
+    // Convert Uint8Array to binary string for btoa. Chunked to avoid
+    // call-stack limits on large payloads.
+    const chunk = 0x8000; // 32 KB — safe below JS engine stack limits
+    let bin = '';
+    for (let i = 0; i < compressed.length; i += chunk) {
+        bin += String.fromCharCode(...compressed.subarray(i, i + chunk));
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Build the full "Share on Nowline" URL for a rendered block.
+ *
+ * Returns `null` when `share` is `false` or `'none'`, signalling that
+ * no anchor should be rendered.
+ */
+export function buildShareLink({ source, sourceUrl, share }) {
+    if (share === false || share === 'none') {
+        return null;
+    }
+    if (typeof share === 'object') {
+        // Template mode: { textUrl, remoteUrl }
+        if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+            return share.remoteUrl.replace('{url}', encodeURIComponent(sourceUrl));
+        }
+        return share.textUrl.replace('{text}', _encodePayload(source));
+    }
+    // share === true → DEFAULT_SHARE_BASE; share is a string → custom base URL
+    const base = share === true ? DEFAULT_SHARE_BASE : share;
+    const url = new URL(base);
+    if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+        url.hash = `url=${encodeURIComponent(sourceUrl)}`;
+    }
+    else {
+        url.hash = `text=${_encodePayload(source)}`;
+    }
+    return url.toString();
+}
+function _isHttps(url) {
+    try {
+        return new URL(url).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=share.js.map

package/dist/share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.js","sourceRoot":"","sources":["../src/share.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kDAAkD;AAClD,EAAE;AACF,4DAA4D;AAC5D,wCAAwC;AACxC,qBAAqB;AACrB,EAAE;AACF,mEAAmE;AACnE,mEAAmE;AACnE,WAAW;AACX,EAAE;AACF,mDAAmD;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AAejE;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACrC,OAAO,SAAS,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,iEAAiE;AACjE,SAAS,cAAc,CAAC,MAAc;IAClC,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,iEAAiE;IACjE,uCAAuC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,4CAA4C;IAClE,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAChD,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAyB;IAC9E,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,wCAAwC;QACxC,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACjD,OAAO,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,2EAA2E;IAC3E,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC;IACzD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAE1B,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,GAAG,CAAC,IAAI,GAAG,OAAO,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;IACtD,CAAC;SAAM,CAAC;QACJ,GAAG,CAAC,IAAI,GAAG,QAAQ,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;IAChD,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AAC1B,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IACzB,IAAI,CAAC;QACD,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nowline/embed",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Browser embed bundle for Nowline. Drop a <script> tag and ```nowline``` blocks render in place.",
   "license": "Apache-2.0",
   "engines": {
@@ -39,11 +39,12 @@
     "cdn"
   ],
   "dependencies": {
+    "fflate": "^0.8.3",
     "langium": "~4.2.4",
-    "@nowline/browser": "0.4.1",
-    "@nowline/core": "0.4.1",
-    "@nowline/renderer": "0.4.1",
-    "@nowline/layout": "0.4.1"
+    "@nowline/core": "0.4.2",
+    "@nowline/layout": "0.4.2",
+    "@nowline/renderer": "0.4.2",
+    "@nowline/browser": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/src/auth/firebase-auth.client.ts

@@ -144,20 +144,24 @@ export function startDevAuthGate(): void {
 
     const provider = new GoogleAuthProvider();
 
-    const handleSignIn = async (): Promise<void> => {
-        try {
-            await signInWithPopup(auth as Auth, provider);
-        } catch (err) {
-            console.error('[nowline-embed-dev-auth-gate] Sign-in failed:', err);
-        }
+    const handleSignIn = (): void => {
+        void (async () => {
+            try {
+                await signInWithPopup(auth as Auth, provider);
+            } catch (err) {
+                console.error('[nowline-embed-dev-auth-gate] Sign-in failed:', err);
+            }
+        })();
     };
 
-    const handleSignOut = async (): Promise<void> => {
-        try {
-            await signOut(auth as Auth);
-        } catch (err) {
-            console.error('[nowline-embed-dev-auth-gate] Sign-out failed:', err);
-        }
+    const handleSignOut = (): void => {
+        void (async () => {
+            try {
+                await signOut(auth as Auth);
+            } catch (err) {
+                console.error('[nowline-embed-dev-auth-gate] Sign-out failed:', err);
+            }
+        })();
     };
 
     onAuthStateChanged(auth as Auth, (user: User | null) => {

package/src/auto-scan.ts

@@ -5,6 +5,7 @@
 
 import type { ThemeName } from '@nowline/layout';
 import { type EmbedRenderOptions, renderSource } from './pipeline.js';
+import { buildShareLink, type ShareOption } from './share.js';
 
 export interface AutoScanInputs {
     selector: string;
@@ -12,6 +13,16 @@ export interface AutoScanInputs {
     locale?: string;
     width?: number;
     today?: Date;
+    /**
+     * Controls the "Share on Nowline" anchor appended after each rendered
+     * SVG. Defaults to `true` when omitted (mirrors the config default).
+     */
+    share?: ShareOption;
+    /**
+     * Global source URL for all blocks. Per-block `data-nowline-source-url`
+     * overrides this for individual blocks.
+     */
+    sourceUrl?: string;
     /**
      * Document to scan. Defaults to `globalThis.document`. Tests inject
      * a happy-dom document; the IIFE running on a real page picks up
@@ -40,6 +51,9 @@ export async function runAutoScan(inputs: AutoScanInputs): Promise<AutoScanResul
     let failed = 0;
     const baseRunId = ++runCounter;
 
+    // share defaults to true when omitted (mirrors config.share default)
+    const share: ShareOption = inputs.share ?? true;
+
     const tasks: Array<Promise<void>> = [];
     let blockIndex = 0;
     for (const code of Array.from(blocks)) {
@@ -56,11 +70,39 @@ export async function runAutoScan(inputs: AutoScanInputs): Promise<AutoScanResul
             today: inputs.today,
             idPrefix,
         };
+
+        // Capture DOM position before the async render. outerHTML replacement
+        // detaches `target` from the tree, so parent and nextSibling must be
+        // read now. The share anchor is inserted at the saved nextSibling
+        // position, which lands it as the immediate next sibling of the SVG.
+        const parent = target.parentElement;
+        const nextSibling = target.nextSibling;
+
+        // Per-block resolution order: data-nowline-source-url → global sourceUrl
+        const perBlockUrl = code.getAttribute('data-nowline-source-url') ?? undefined;
+        const resolvedSourceUrl = perBlockUrl ?? inputs.sourceUrl;
+
         tasks.push(
             renderSource(source, opts).then(
                 (svg) => {
                     replaceWithSvg(target, svg);
                     rendered++;
+                    if (parent !== null) {
+                        const href = buildShareLink({
+                            source,
+                            sourceUrl: resolvedSourceUrl,
+                            share,
+                        });
+                        if (href !== null) {
+                            const a = doc.createElement('a');
+                            a.className = 'nowline-share';
+                            a.href = href;
+                            a.target = '_blank';
+                            a.rel = 'noopener noreferrer';
+                            a.textContent = 'Share on Nowline';
+                            parent.insertBefore(a, nextSibling);
+                        }
+                    }
                 },
                 (err: unknown) => {
                     failed++;

package/src/index.ts

@@ -31,9 +31,16 @@ import {
     parseSource,
     renderSource,
 } from './pipeline.js';
+import type { ShareOption } from './share.js';
 import { type EmbedTheme, effectiveTheme, resolveSystemTheme } from './theme.js';
 
-export { type AutoScanResult, type EmbedParseResult, EmbedRenderError, type EmbedTheme };
+export {
+    type AutoScanResult,
+    type EmbedParseResult,
+    EmbedRenderError,
+    type EmbedTheme,
+    type ShareOption,
+};
 
 /**
  * Bundle provenance, mirroring the legal-comment banner that
@@ -71,6 +78,21 @@ export interface InitializeOptions {
     width?: number;
     /** Pin a `today` for deterministic snapshots; defaults to live `new Date()` per render. */
     today?: Date;
+    /**
+     * Controls the "Share on Nowline" anchor appended after each rendered SVG.
+     * - `true` (default) — link to `https://free.nowline.io/open#text=…`.
+     * - string — a custom base URL (may include a path); the fragment is appended.
+     * - `false` / `'none'` — no anchor rendered.
+     * - `{ textUrl, remoteUrl }` — template with `{text}` / `{url}` substitution.
+     */
+    share?: ShareOption;
+    /**
+     * Global source URL for all blocks on the page. When set, share links
+     * use `#url=<sourceUrl>` instead of `#text=` (inline encoding).
+     * Per-block `data-nowline-source-url` overrides this for individual blocks.
+     * Only `https:` URLs are emitted as `#url=`.
+     */
+    sourceUrl?: string;
 }
 
 interface ResolvedConfig {
@@ -82,6 +104,10 @@ interface ResolvedConfig {
     today?: Date;
     /** System theme captured at init; not reactive to OS theme flips mid-session. */
     systemTheme: 'light' | 'dark';
+    /** Controls the "Share on Nowline" anchor. Defaults to `true`. */
+    share: ShareOption;
+    /** Global canonical source URL; per-block `data-nowline-source-url` takes priority. */
+    sourceUrl?: string;
 }
 
 const initialConfig: ResolvedConfig = {
@@ -89,6 +115,7 @@ const initialConfig: ResolvedConfig = {
     startOnLoad: true,
     selector: DEFAULT_SELECTOR,
     systemTheme: resolveSystemTheme(),
+    share: true,
 };
 
 let config: ResolvedConfig = { ...initialConfig };
@@ -102,6 +129,8 @@ export function initialize(options: InitializeOptions = {}): void {
         locale: options.locale ?? config.locale,
         width: options.width ?? config.width,
         today: options.today ?? config.today,
+        share: options.share ?? config.share,
+        sourceUrl: options.sourceUrl ?? config.sourceUrl,
         // Re-read `prefers-color-scheme` on every initialize() so callers
         // who explicitly want the latest system theme can ask for it by
         // calling initialize() again. Auto-scan paths still use the value
@@ -154,6 +183,8 @@ export async function init(overrides?: Partial<AutoScanInputs>): Promise<AutoSca
         locale: overrides?.locale ?? config.locale,
         width: overrides?.width ?? config.width,
         today: overrides?.today ?? config.today,
+        share: overrides?.share ?? config.share,
+        sourceUrl: overrides?.sourceUrl ?? config.sourceUrl,
         document: overrides?.document,
     };
     return runAutoScan(inputs);

package/src/share.ts

@@ -0,0 +1,109 @@
+// Share-link generation for the "Share on Nowline" anchor that the
+// auto-scan loop appends after each rendered SVG.
+//
+// Encoding grammar (normative — defined in specs/embed.md):
+//   #text=base64url(zlib(utf8(source)))
+//   #url=<https-url>
+//
+// zlib = RFC 1950 via fflate zlibSync (byte-compatible with native
+// CompressionStream('deflate')); base64url strips padding and maps
+// +→- /→_.
+//
+// Sync, works on every browser, no feature-detect.
+
+import { zlibSync } from 'fflate';
+
+/** Default share destination — the Nowline Free app's open route. */
+export const DEFAULT_SHARE_BASE = 'https://free.nowline.io/open';
+
+/**
+ * The `share` initialize option selects where share links point.
+ *
+ * - `true` — use DEFAULT_SHARE_BASE (the default).
+ * - `string` — a base URL with optional path; built via the URL API so
+ *   `https://foo.com/open` → `https://foo.com/open#text=…`.
+ * - `false` / `'none'` — disable the share anchor entirely.
+ * - `{ textUrl, remoteUrl }` — escape hatch for non-hash URL shapes;
+ *   `{text}` substituted with the base64url payload, `{url}` with the
+ *   percent-encoded source URL.
+ */
+export type ShareOption = boolean | 'none' | string | { textUrl: string; remoteUrl: string };
+
+/**
+ * Encode source text → `#text=<base64url(zlib(utf8(source)))>`.
+ *
+ * The return value includes the `#text=` key so callers can use it
+ * directly as a URL fragment.
+ *
+ * Sync, single code path, no feature-detect.
+ */
+export function encodeText(source: string): string {
+    return `#text=${_encodePayload(source)}`;
+}
+
+/** base64url(zlib(utf8(source))) without the `#text=` prefix. */
+function _encodePayload(source: string): string {
+    const bytes = new TextEncoder().encode(source);
+    const compressed = zlibSync(bytes);
+    // Convert Uint8Array to binary string for btoa. Chunked to avoid
+    // call-stack limits on large payloads.
+    const chunk = 0x8000; // 32 KB — safe below JS engine stack limits
+    let bin = '';
+    for (let i = 0; i < compressed.length; i += chunk) {
+        bin += String.fromCharCode(...compressed.subarray(i, i + chunk));
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export interface BuildShareLinkOptions {
+    /** The roadmap source text (used to build the #text= fragment). */
+    source: string;
+    /**
+     * Resolved source URL for the block (per-block → global → undefined).
+     * Only `https:` URLs are emitted as `#url=`; anything else falls
+     * back to the inline `#text=` encoding.
+     */
+    sourceUrl?: string | undefined;
+    /** The `share` option from InitializeOptions. */
+    share: ShareOption;
+}
+
+/**
+ * Build the full "Share on Nowline" URL for a rendered block.
+ *
+ * Returns `null` when `share` is `false` or `'none'`, signalling that
+ * no anchor should be rendered.
+ */
+export function buildShareLink({ source, sourceUrl, share }: BuildShareLinkOptions): string | null {
+    if (share === false || share === 'none') {
+        return null;
+    }
+
+    if (typeof share === 'object') {
+        // Template mode: { textUrl, remoteUrl }
+        if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+            return share.remoteUrl.replace('{url}', encodeURIComponent(sourceUrl));
+        }
+        return share.textUrl.replace('{text}', _encodePayload(source));
+    }
+
+    // share === true → DEFAULT_SHARE_BASE; share is a string → custom base URL
+    const base = share === true ? DEFAULT_SHARE_BASE : share;
+    const url = new URL(base);
+
+    if (sourceUrl !== undefined && _isHttps(sourceUrl)) {
+        url.hash = `url=${encodeURIComponent(sourceUrl)}`;
+    } else {
+        url.hash = `text=${_encodePayload(source)}`;
+    }
+
+    return url.toString();
+}
+
+function _isHttps(url: string): boolean {
+    try {
+        return new URL(url).protocol === 'https:';
+    } catch {
+        return false;
+    }
+}