@rasamjs/core 0.1.2 → 0.2.0

package/src/interchange/markup.ts

@@ -8,6 +8,31 @@ import { InterchangeDom } from './dom.js';
 import { preflight, reconstruct } from './reconstruct.js';
 import { validateImportContent } from './policy.js';
 import type { ExportOptions, ImportOptions } from './types.js';
+import { BBox } from '../math/bbox.js';
+import { isNestedViewport, viewportLength } from '../services/viewport.js';
+import { Attributes } from '../dom/attributes.js';
+
+function frameContent(source: AnyNode, envelope: SVGElement, padding: number): void {
+  const bounds = source.bounds('root');
+  if (bounds.status === 'unavailable')
+    throw new Error(`Cannot frame SVG content: ${bounds.reason}`);
+  const box =
+    'box' in bounds
+      ? bounds.box
+      : {
+          x: 0,
+          y: 0,
+          width: BBox.numeric(source.context.root?.getAttributeValue('width'), 800) ?? 800,
+          height: BBox.numeric(source.context.root?.getAttributeValue('height'), 600) ?? 600,
+        };
+  const width = box.width + padding * 2,
+    height = box.height + padding * 2;
+  if (![box.x - padding, box.y - padding, width, height].every(Number.isFinite))
+    throw new RangeError('SVG content frame must be finite');
+  envelope.setAttribute('viewBox', `${box.x - padding} ${box.y - padding} ${width} ${height}`);
+  envelope.setAttribute('width', String(width));
+  envelope.setAttribute('height', String(height));
+}
 
 export function exportSvg(source: AnyNode, options: ExportOptions = {}): string {
   source.assertLive();
@@ -15,6 +40,13 @@ export function exportSvg(source: AnyNode, options: ExportOptions = {}): string
     throw new TypeError('Unknown SVG export format');
   if (options.resources !== undefined && !['referenced', 'none'].includes(options.resources))
     throw new TypeError('Unknown export resource policy');
+  if (options.frame !== undefined && options.frame !== 'content')
+    throw new TypeError('Unknown SVG frame');
+  if (options.frame && options.format === 'subtree')
+    throw new TypeError('Content framing requires a document export');
+  const padding = options.padding ?? 0;
+  if (!Number.isFinite(padding) || padding < 0)
+    throw new RangeError('SVG padding must be nonnegative and finite');
   source.flush();
   const dependencies = options.resources === 'none' ? [] : dependencyRoots(source, 'local');
   const copies = new Map<AnyNode, SVGElement>();
@@ -25,20 +57,45 @@ export function exportSvg(source: AnyNode, options: ExportOptions = {}): string
     return InterchangeDom.serialize(element);
   }
   const document = element.ownerDocument;
+  const framedSubtree = options.frame === 'content' && source !== source.context.root;
   const envelope =
-    element.localName === 'svg' ? element : document.createElementNS(SVG_NAMESPACE, 'svg');
+    element.localName === 'svg' && !framedSubtree
+      ? element
+      : document.createElementNS(SVG_NAMESPACE, 'svg');
   if (envelope !== element) {
     for (const name of ['width', 'height', 'viewBox', 'preserveAspectRatio']) {
       const value = source.context.root?.getAttributeValue(name);
       if (value !== undefined) envelope.setAttribute(name, String(value));
     }
-    envelope.append(element);
+    if (framedSubtree && source.parent) {
+      // The snapshot retains its own transform and any nested SVG viewport. Only
+      // the omitted ancestors need mapping into the document-space content frame.
+      const mapping = document.createElementNS(SVG_NAMESPACE, 'g');
+      mapping.setAttribute('transform', source.context.bounds.matrix(source.parent).toString());
+      mapping.append(element);
+      envelope.append(mapping);
+    } else envelope.append(element);
   }
   if (dependencies.length) {
     const defs = document.createElementNS(SVG_NAMESPACE, 'defs');
     for (const dependency of dependencies) defs.append(snapshot(dependency, copies));
     envelope.prepend(defs);
   }
+  if (options.frame === 'content') {
+    frameContent(source, envelope, padding);
+    // Reframing changes percentage bases. Preserve each copied nested viewport's
+    // original placement and dimensions, including omitted 100% sizes.
+    for (const [node, copy] of copies) {
+      if (!isNestedViewport(node)) continue;
+      for (const name of ['x', 'y', 'width', 'height'] as const) {
+        const axis = name === 'x' || name === 'width' ? 'width' : 'height';
+        copy.setAttribute(
+          name,
+          String(viewportLength(node, name, axis, name === axis ? '100%' : 0)),
+        );
+      }
+    }
+  }
   return InterchangeDom.serialize(envelope);
 }
 
@@ -51,8 +108,22 @@ export function importSvg(
     assertCanAddChildren(parent);
     const index = options.index ?? parent.children.length;
     validateIndex(index, parent.children.length);
-    const roots = InterchangeDom.parse(parent.el, markup);
+    if (
+      options.document !== undefined &&
+      typeof options.document !== 'boolean' &&
+      !['presentation', 'replace'].includes(options.document)
+    )
+      throw new TypeError('Unknown document import mode');
+    if (
+      options.document === 'replace' &&
+      (parent !== parent.context.root || parent.children.length)
+    )
+      throw new TypeError('Document replacement requires an empty owning drawing');
+    let roots = InterchangeDom.parse(parent.el, markup, !!options.document);
     validateImportContent(roots, options);
+    const replace =
+      options.document === 'replace' && roots.length === 1 && roots[0].localName === 'svg';
+    if (options.document) roots = InterchangeDom.unwrap(roots, options.document !== true);
     preflight(parent.context, roots);
     remapIds(parent, roots);
     return reconstruct(parent, roots, (nodes) => {
@@ -60,6 +131,9 @@ export function importSvg(
       for (const node of nodes) parent[validateChild](node);
       for (let position = 0; position < nodes.length; position++)
         parent.add(nodes[position], index + position);
+      if (replace)
+        for (const name of Attributes.common)
+          if (!['id', 'class'].includes(name)) parent.setAttributeValue(name, undefined);
       return Object.freeze(nodes);
     });
   });

package/src/interchange/policy.ts

@@ -89,6 +89,12 @@ function validateUrl(tag: string, name: string, value: string, options: ImportOp
   if (reference) return;
   if (name === 'href') {
     if (value === '') return;
+    // Image documents are passive resources; keep embedded image files restorable.
+    if (
+      tag === 'image' &&
+      /^data:image\/(?:png|jpe?g|gif|webp|avif|svg\+xml)(?:;[^,]*)?,/i.test(value)
+    )
+      return;
     if (
       options.externalUrls === 'http' &&
       ['image', 'a', 'use'].includes(tag) &&

package/src/interchange/types.ts

@@ -10,9 +10,18 @@ export interface ExportOptions {
   format?: 'document' | 'subtree';
   /** Include reachable typed and unambiguous local references. CSS URLs are not traversed. */
   resources?: 'referenced' | 'none';
+  /** Frame geometric content in document coordinates rather than the current camera. */
+  frame?: 'content';
+  /** Nonnegative drawing units around a content frame; defaults to zero. */
+  padding?: number;
 }
 export interface ImportOptions {
   index?: number;
-  /** External URLs are rejected by default. Opt in to absolute HTTP(S) image/link/Use URLs. */
+  /** true unwraps children; 'presentation' retains scoped root attributes without
+   * the viewport. 'replace' additionally clears configured root presentation for a
+   * full document, and requires an empty owning drawing. Fragments keep defaults. */
+  document?: boolean | 'presentation' | 'replace';
+  /** External URLs are rejected by default; embedded data images are allowed on image elements.
+   * Opt in to absolute HTTP(S) image/link/Use URLs. */
   externalUrls?: 'reject' | 'http';
 }

package/src/mixins/transformable.ts

@@ -53,8 +53,8 @@ export const Transformable: MixinTransformable = (BaseClass) => {
     matrix(): Matrix;
     matrix(value: Matrix | MatrixValues): this;
     matrix(value?: Matrix | MatrixValues): Matrix | this {
+      if (value === undefined) return this.localMatrix();
       return mutation(this, () => {
-        if (value === undefined) return this.localMatrix();
         this.assertLive();
         const matrix = Matrix.from(value);
         this.#matrixMode = true;
@@ -110,33 +110,31 @@ export const Transformable: MixinTransformable = (BaseClass) => {
     transformState(): TransformState;
     transformState(state: TransformState): this;
     transformState(state?: TransformState): TransformState | this {
-      return mutation(this, () => {
-        this.assertLive();
-        if (state !== undefined) return this.restoreTransformState(state);
-        const { base, geometry } = this.mappingState();
-        const transform = this.getAttributeValue('transform');
-        const common = {
-          tag: this.context.dom.tag(this.el),
-          transform: transform === undefined ? null : String(transform),
-          geometry: Object.freeze(geometry.toArray()),
-          attributes: geometrySnapshot(this),
-        };
-        if (this.#matrixMode || transform !== this.#lastTransform)
-          return Object.freeze({
-            ...common,
-            mode: 'matrix',
-            matrix: Object.freeze(base.toArray()),
-          });
-        const components = this.components;
+      this.assertLive();
+      if (state !== undefined) return mutation(this, () => this.restoreTransformState(state));
+      const { base, geometry } = this.mappingState();
+      const transform = this.getAttributeValue('transform');
+      const common = {
+        tag: this.context.dom.tag(this.el),
+        transform: transform === undefined ? null : String(transform),
+        geometry: Object.freeze(geometry.toArray()),
+        attributes: geometrySnapshot(this),
+      };
+      if (this.#matrixMode || transform !== this.#lastTransform)
         return Object.freeze({
           ...common,
-          mode: 'components',
-          position: components.position,
-          rotation: components.rotation,
-          scale: components.scale,
-          origin: components.origin,
-          automaticOrigin: !components.explicitOrigin,
+          mode: 'matrix',
+          matrix: Object.freeze(base.toArray()),
         });
+      const components = this.components;
+      return Object.freeze({
+        ...common,
+        mode: 'components',
+        position: components.position,
+        rotation: components.rotation,
+        scale: components.scale,
+        origin: components.origin,
+        automaticOrigin: !components.explicitOrigin,
       });
     }
 

package/src/raster/frame.ts

@@ -0,0 +1,53 @@
+import type { AnyNode } from '../core/types.js';
+import { exportSvg } from '../interchange/markup.js';
+import type { RasterOptions } from './types.js';
+export function prepareRaster(root: AnyNode, options: RasterOptions) {
+  root.assertLive();
+  const document = root.el.ownerDocument,
+    view = document.defaultView;
+  if (!view) throw new Error('Raster export needs a browser document');
+  const type = options.type ?? 'image/png',
+    scale = options.scale ?? 1,
+    frame = options.frame ?? 'content',
+    padding = options.padding ?? 0;
+  if (!['image/png', 'image/webp', 'image/jpeg'].includes(type))
+    throw new TypeError('Unknown raster image type');
+  if (!Number.isFinite(scale) || scale <= 0)
+    throw new RangeError('Raster scale must be positive and finite');
+  if (!Number.isFinite(padding) || padding < 0)
+    throw new RangeError('Raster padding must be nonnegative and finite');
+  if (!['content', 'viewBox'].includes(frame)) throw new TypeError('Unknown raster frame');
+  const background = options.background ?? (type === 'image/jpeg' ? '#ffffff' : undefined);
+  if (
+    background !== undefined &&
+    (typeof background !== 'string' || !view.CSS.supports('color', background))
+  )
+    throw new TypeError('Raster background must be a CSS color');
+  const markup = exportSvg(root, { frame: frame === 'content' ? 'content' : undefined, padding });
+  const svg = new view.DOMParser().parseFromString(markup, 'image/svg+xml').documentElement;
+  const box = svg
+    .getAttribute('viewBox')
+    ?.trim()
+    .split(/[\s,]+/)
+    .map(Number);
+  const extent = root.context.root!.el.getBoundingClientRect();
+  const length = (name: 'width' | 'height', fallback: number) => {
+    const value = svg.getAttribute(name) ?? '';
+    return /^\d+(?:\.\d+)?(?:px)?$/.test(value) ? parseFloat(value) : fallback;
+  };
+  const width = box?.length === 4 ? box[2] : length('width', extent.width),
+    height = box?.length === 4 ? box[3] : length('height', extent.height);
+  const pixels = [Math.ceil(width * scale), Math.ceil(height * scale)];
+  if (
+    !pixels.every((value) => Number.isSafeInteger(value) && value > 0 && value <= 32767) ||
+    pixels[0] * pixels[1] > 16777216
+  )
+    throw new RangeError(
+      'Raster export needs positive dimensions, at most 32767 per axis and 16777216 pixels; reduce scale or add padding to zero-size content',
+    );
+  svg.setAttribute('width', String(pixels[0]));
+  svg.setAttribute('height', String(pixels[1]));
+  if (!box) svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
+  return { document, svg, type, background, width: pixels[0], height: pixels[1] };
+}
+export type RasterSnapshot = ReturnType<typeof prepareRaster>;

package/src/raster/images.ts

@@ -0,0 +1,73 @@
+/** Inline supported image resources; SVG-as-image rendering cannot load external files. */
+const xlink = 'http://www.w3.org/1999/xlink';
+export async function embedImages(
+  svg: Element,
+  document: Document,
+  base: string,
+  ancestors: readonly string[] = [],
+): Promise<void> {
+  const view = document.defaultView!;
+  for (const image of svg.querySelectorAll('image,feImage')) {
+    const href = image.getAttribute('href') ?? image.getAttributeNS(xlink, 'href');
+    if (!href || href.startsWith('#')) continue;
+    const url = new URL(href, base);
+    if (
+      url.protocol !== 'data:' &&
+      (!['http:', 'https:'].includes(url.protocol) || url.origin !== new URL(document.URL).origin)
+    )
+      throw new Error('Raster export supports only same-origin and data-URL images');
+    if (ancestors.length >= 8 || ancestors.includes(url.href))
+      throw new Error('Raster image resources are cyclic or too deeply nested');
+    let blob: Blob;
+    try {
+      const response = await view.fetch(
+        url.href,
+        url.protocol === 'data:'
+          ? {}
+          : { mode: 'same-origin', credentials: 'same-origin', redirect: 'error' },
+      );
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      blob = await response.blob();
+    } catch (cause) {
+      throw new Error('Cannot load a raster image resource', { cause });
+    }
+    const mime = blob.type.split(';')[0].toLowerCase();
+    if (
+      ![
+        'image/png',
+        'image/jpeg',
+        'image/webp',
+        'image/gif',
+        'image/avif',
+        'image/svg+xml',
+      ].includes(mime)
+    )
+      throw new Error('Unsupported raster image resource type');
+    if (mime === 'image/svg+xml') {
+      const nested = new view.DOMParser().parseFromString(await blob.text(), 'image/svg+xml');
+      if (nested.querySelector('parsererror') || nested.documentElement.localName !== 'svg')
+        throw new Error('Invalid SVG image resource');
+      await embedImages(
+        nested.documentElement,
+        document,
+        url.protocol === 'data:' ? base : url.href,
+        [...ancestors, url.href],
+      );
+      blob = new view.Blob([new view.XMLSerializer().serializeToString(nested)], { type: mime });
+    }
+    const data = await new Promise<string>((resolve, reject) => {
+      const reader = new view.FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => reject(new Error('Cannot encode a raster image resource'));
+      reader.readAsDataURL(blob);
+    });
+    await new Promise<void>((resolve, reject) => {
+      const decoded = new view.Image();
+      decoded.onload = () => resolve();
+      decoded.onerror = () => reject(new Error('Cannot decode a raster image resource'));
+      decoded.src = data;
+    });
+    image.removeAttributeNS(xlink, 'href');
+    image.setAttribute('href', data);
+  }
+}

package/src/raster/render.ts

@@ -0,0 +1,45 @@
+import type { RasterSnapshot } from './frame.js';
+export async function renderRaster({
+  document,
+  svg,
+  type,
+  background,
+  width,
+  height,
+}: RasterSnapshot): Promise<Blob> {
+  const view = document.defaultView!;
+  const url = view.URL.createObjectURL(
+    new view.Blob([new view.XMLSerializer().serializeToString(svg)], { type: 'image/svg+xml' }),
+  );
+  try {
+    const image = new view.Image();
+    await new Promise<void>((resolve, reject) => {
+      image.onload = () => resolve();
+      image.onerror = () => reject(new Error('Cannot decode SVG for raster export'));
+      image.src = url;
+    });
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Raster export needs a 2D canvas context');
+    if (background !== undefined) {
+      context.fillStyle = background;
+      context.fillRect(0, 0, canvas.width, canvas.height);
+    }
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    return await new Promise<Blob>((resolve, reject) =>
+      canvas.toBlob((blob) => {
+        if (!blob) reject(new Error('Browser could not encode the raster image'));
+        else if (blob.type !== type) reject(new Error(`Browser cannot encode ${type}`));
+        else resolve(blob);
+      }, type),
+    );
+  } catch (cause) {
+    if ((cause as { name?: string })?.name === 'SecurityError')
+      throw new Error('Cannot export image: canvas is tainted by cross-origin content', { cause });
+    throw cause;
+  } finally {
+    view.URL.revokeObjectURL(url);
+  }
+}

package/src/raster/types.ts

@@ -0,0 +1,9 @@
+export interface RasterOptions {
+  readonly type?: 'image/png' | 'image/webp' | 'image/jpeg';
+  readonly scale?: number;
+  readonly background?: string;
+  /** Content bounds by default; viewBox exports the current document camera. */
+  readonly frame?: 'content' | 'viewBox';
+  /** Drawing units around content bounds, default zero. */
+  readonly padding?: number;
+}

package/src/raster.ts

@@ -0,0 +1,13 @@
+import type { AnyNode } from './core/types.js';
+import type { RasterOptions } from './raster/types.js';
+import { prepareRaster } from './raster/frame.js';
+import { embedImages } from './raster/images.js';
+import { renderRaster } from './raster/render.js';
+export type { RasterOptions };
+
+/** Snapshot and render a passive SVG document without changing its camera or model. */
+export async function exportImage(root: AnyNode, options: RasterOptions = {}): Promise<Blob> {
+  const snapshot = prepareRaster(root, options);
+  await embedImages(snapshot.svg, snapshot.document, root.el.baseURI);
+  return renderRaster(snapshot);
+}

package/src/resources/references.ts

@@ -35,7 +35,11 @@ export function classifyReference(attribute: string, value: unknown): LocalRefer
   attribute = Attributes.normalizeName(attribute);
   if (typeof value !== 'string') return null;
   const source = value.replace(/^[ \t\r\n\f]+|[ \t\r\n\f]+$/g, '');
-  if (attribute === 'href') {
+  if (
+    attribute === 'href' ||
+    attribute === 'data-rasam-connector-start' ||
+    attribute === 'data-rasam-connector-end'
+  ) {
     const match = /^#([^\s#<>"'()\\\u0000-\u001f\u007f]+)$/.exec(source);
     return localReference('href', match?.[1]);
   }

package/src/services/viewport.ts

@@ -17,7 +17,8 @@ export function unresolved(error: unknown): Bounds {
   throw error;
 }
 
-function length(node: AnyNode, name: string, axis: Axis, fallback: unknown): number {
+/** Resolve an authored viewport length against its original ancestor viewport. */
+export function viewportLength(node: AnyNode, name: string, axis: Axis, fallback: unknown): number {
   return userLength(node.getAttributeValue(name) ?? fallback, () => {
     // Percentages use the nearest ancestor viewport's viewBox, or its size without one.
     let viewport = node === node.context.root ? null : node.parent;
@@ -30,15 +31,15 @@ function length(node: AnyNode, name: string, axis: Axis, fallback: unknown): num
 
 /** A viewport's width or height in its parent's user units; omitted sizes are 100%. */
 export function viewportSize(node: AnyNode, axis: Axis): number {
-  const size = length(node, axis, axis, '100%');
+  const size = viewportLength(node, axis, axis, '100%');
   if (size < 0) throw new ViewportError('Negative viewport size');
   return size;
 }
 
 /** Placement and viewBox transform from a nested viewport's user space to its parent's. */
 export function viewportMapping(node: AnyNode): Matrix {
-  const x = length(node, 'x', 'width', 0),
-    y = length(node, 'y', 'height', 0),
+  const x = viewportLength(node, 'x', 'width', 0),
+    y = viewportLength(node, 'y', 'height', 0),
     viewBox = node.getAttributeValue('viewBox');
   return viewBox === undefined
     ? Matrix.translation(x, y)

package/src/text/content.ts

@@ -7,6 +7,7 @@ import { assertCanAddChildren, validateChild } from '../mixins/parent-internals.
 import { destroySubtrees } from '../core/destruction.js';
 import { TextDom } from '../dom/text.js';
 import type { TextPolicies } from '../changes/types.js';
+import { textContents } from './policies.js';
 
 class TextSlot implements TextBinding {
   active = true;
@@ -275,25 +276,14 @@ export class TextContent {
   }
 }
 
-const contents = new WeakMap<AnyNode, TextContent>();
 export function contentFor(host: ParentNode): TextContent {
-  let content = contents.get(host);
+  let content = textContents.get(host);
   if (!content) {
     content = new TextContent(host);
-    contents.set(host, content);
+    textContents.set(host, content);
   }
   return content;
 }
 export function refreshLines(host: AnyNode): void {
-  contents.get(host)?.refreshLines();
-}
-
-/** Internal reconstruction bridge; copies policies onto fresh children, never callback closures. */
-export function copyTextPolicies(
-  source: AnyNode,
-  target: ParentNode,
-  copies: ReadonlyMap<AnyNode, AnyNode>,
-): void {
-  const content = contents.get(source);
-  if (content) content.copyLinesTo(contentFor(target), copies);
+  textContents.get(host)?.refreshLines();
 }

package/src/text/policies.ts

@@ -0,0 +1,18 @@
+import type { AnyNode } from '../core/types.js';
+import type { TextContent } from './content.js';
+
+/** Shared state without retaining the rich-text implementation in interchange bundles. */
+export const textContents = new WeakMap<AnyNode, TextContent>();
+
+/** Copies policies onto reconstructed text children, never callback closures. */
+export function copyTextPolicies(
+  source: AnyNode,
+  target: AnyNode,
+  copies: ReadonlyMap<AnyNode, AnyNode>,
+): void {
+  const content = textContents.get(source);
+  if (!content) return;
+  const destination = textContents.get(target);
+  if (!destination) throw new TypeError('Clone target must support the source text content');
+  content.copyLinesTo(destination, copies);
+}