@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/dist/Markdown/plugins/semanticFence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file semanticFence.ts
+ * @input Declared fenced-code languages and typed extension-node factories
+ * @output Immutable Markdown transform that annotates eligible canonical code nodes
+ * @position Optional helper layer compiled onto the core transform protocol
+ */
+import type { MarkdownAstCode } from '../ast';
+import { type MarkdownExtensionNode, type MarkdownPluginData, type MarkdownTransform } from './protocol';
+export interface MarkdownFenceContext<Language extends string> {
+    readonly code: string;
+    readonly language: Language;
+    readonly meta?: string;
+}
+export type MarkdownFenceNode<Node extends MarkdownExtensionNode> = Node & {
+    readonly type: 'extension';
+    readonly display: 'block';
+    readonly position?: never;
+    readonly source?: never;
+};
+export interface MarkdownFenceTransformOptions<Languages extends readonly [string, ...string[]], Node extends MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>> {
+    /** Exact, case-sensitive fenced-code language identifiers this helper owns. */
+    readonly languages: Languages;
+    /**
+     * Creates typed semantic data for an eligible fence. Return null or undefined
+     * to retain Markdown's ordinary CodeBlock rendering.
+     */
+    readonly createNode: (context: MarkdownFenceContext<Languages[number]>) => MarkdownFenceNode<Node> | null | undefined;
+}
+interface MarkdownFenceProposal {
+    readonly node: MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>;
+}
+/** @internal Returns the first transform-owned proposal attached to a code node. */
+export declare function getMarkdownFenceProposal(node: MarkdownAstCode): MarkdownFenceProposal | undefined;
+export declare function createMarkdownFenceTransform<const Languages extends readonly [string, ...string[]], const Node extends MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>>(options: MarkdownFenceTransformOptions<Languages, Node>): MarkdownTransform<Node>;
+export {};
+//# sourceMappingURL=semanticFence.d.ts.map

package/dist/Markdown/plugins/semanticFence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticFence.d.ts","sourceRoot":"","sources":["../../../src/Markdown/plugins/semanticFence.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,eAAe,EAEhB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,MAAM;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,qBAAqB,IAAI,IAAI,GAAG;IACzE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,6BAA6B,CAC5C,SAAS,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EAChD,IAAI,SAAS,qBAAqB,CAChC,MAAM,EACN,MAAM,EACN,kBAAkB,EAClB,OAAO,CACR;IAED,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,CACnB,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAC7C,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CACjD;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAClC,MAAM,EACN,MAAM,EACN,kBAAkB,EAClB,OAAO,CACR,CAAC;CACH;AAQD,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,eAAe,GACpB,qBAAqB,GAAG,SAAS,CAEnC;AAgRD,wBAAgB,4BAA4B,CAC1C,KAAK,CAAC,SAAS,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EACtD,KAAK,CAAC,IAAI,SAAS,qBAAqB,CACtC,MAAM,EACN,MAAM,EACN,kBAAkB,EAClB,OAAO,CACR,EAED,OAAO,EAAE,6BAA6B,CAAC,SAAS,EAAE,IAAI,CAAC,GACtD,iBAAiB,CAAC,IAAI,CAAC,CAgEzB"}

package/dist/Markdown/plugins/semanticFence.js

@@ -0,0 +1,213 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file semanticFence.ts
+ * @input Declared fenced-code languages and typed extension-node factories
+ * @output Immutable Markdown transform that annotates eligible canonical code nodes
+ * @position Optional helper layer compiled onto the core transform protocol
+ */
+
+import { getMarkdownHelperOwnership, markMarkdownTransformClaim, markMarkdownTransformTrusted } from "./protocol.js";
+const markdownFenceProposal = Symbol('MarkdownFenceProposal');
+/** @internal Returns the first transform-owned proposal attached to a code node. */
+export function getMarkdownFenceProposal(node) {
+  return node[markdownFenceProposal];
+}
+function cloneNestedPluginData(value, parent, ancestors) {
+  if (value == null || typeof value !== 'object') {
+    return clonePluginData(value, ancestors);
+  }
+  const nestedAncestors = new Set(ancestors);
+  nestedAncestors.add(parent);
+  return clonePluginData(value, nestedAncestors);
+}
+function clonePluginData(value, ancestors) {
+  if (value == null || typeof value === 'boolean' || typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError('invalid plugin data');
+    }
+    return value;
+  }
+  if (typeof value !== 'object' || ancestors?.has(value) === true || !Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError('invalid plugin data');
+  }
+  let clone;
+  if (Array.isArray(value)) {
+    const items = new Array(value.length);
+    for (let index = 0; index < value.length; index++) {
+      if (index in value) {
+        items[index] = cloneNestedPluginData(value[index], value, ancestors);
+      }
+    }
+    clone = Object.freeze(items);
+  } else {
+    const record = {};
+    for (const key in value) {
+      const nested = cloneNestedPluginData(value[key], value, ancestors);
+      if (key === '__proto__') {
+        Object.defineProperty(record, key, {
+          configurable: true,
+          enumerable: true,
+          value: nested,
+          writable: true
+        });
+      } else {
+        record[key] = nested;
+      }
+    }
+    clone = Object.freeze(record);
+  }
+  return clone;
+}
+function createProposal(node, pluginName, hasRenderer) {
+  if (node == null || typeof node !== 'object' || node.type !== 'extension' || node.plugin !== pluginName || typeof node.name !== 'string' || node.name.trim() === '' ||
+  // Every extension node must have a renderer and a text projection
+  // (FR14). Checking it here is what lets Core run this helper on its
+  // trusted path: the node is fully validated before it is inserted.
+  !hasRenderer(node.name) || node.display !== 'block' || 'source' in node || 'position' in node) {
+    throw new TypeError('Markdown fence createNode must return an owned block extension node with finite data and a registered renderer');
+  }
+  let data;
+  try {
+    data = clonePluginData(node.data);
+  } catch {
+    throw new TypeError('Markdown fence createNode must return an owned block extension node with finite data and a registered renderer');
+  }
+  return Object.freeze({
+    node: Object.freeze({
+      type: 'extension',
+      plugin: node.plugin,
+      name: node.name,
+      display: 'block',
+      data
+    })
+  });
+}
+function isPromiseLike(value) {
+  return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
+}
+function consumeInvalidAsyncNode(value, report) {
+  void Promise.resolve(value).then(() => report('Markdown fence createNode returned a Promise'), () => report('Markdown fence createNode Promise rejected'));
+}
+function annotateCode(node, languages, pluginName, hasRenderer, createNode, report) {
+  if (node.lang == null || !languages.has(node.lang) || getMarkdownFenceProposal(node) != null) {
+    return node;
+  }
+  const proposalNode = createNode(Object.freeze({
+    code: node.value,
+    language: node.lang,
+    ...(node.meta == null ? {} : {
+      meta: node.meta
+    })
+  }));
+  if (isPromiseLike(proposalNode)) {
+    consumeInvalidAsyncNode(proposalNode, report);
+    throw new TypeError('Markdown fence createNode must be synchronous');
+  }
+  if (proposalNode == null) {
+    return node;
+  }
+  const annotated = {
+    ...node
+  };
+  Object.defineProperty(annotated, markdownFenceProposal, {
+    configurable: false,
+    enumerable: true,
+    value: createProposal(proposalNode, pluginName, hasRenderer),
+    writable: false
+  });
+  return annotated;
+}
+function transformBlocks(blocks, languages, pluginName, hasRenderer, createNode, report) {
+  let next;
+  for (let index = 0; index < blocks.length; index++) {
+    const block = blocks[index];
+    let replacement;
+    switch (block.type) {
+      case 'code':
+        replacement = annotateCode(block, languages, pluginName, hasRenderer, createNode, report);
+        break;
+      case 'blockquote':
+        {
+          const children = transformBlocks(block.children, languages, pluginName, hasRenderer, createNode, report);
+          replacement = children === block.children ? block : {
+            ...block,
+            children
+          };
+          break;
+        }
+      case 'list':
+        {
+          let items;
+          for (let itemIndex = 0; itemIndex < block.children.length; itemIndex++) {
+            const item = block.children[itemIndex];
+            const itemChildren = transformBlocks(item.children, languages, pluginName, hasRenderer, createNode, report);
+            if (itemChildren === item.children) {
+              items?.push(item);
+              continue;
+            }
+            items ??= block.children.slice(0, itemIndex);
+            items.push({
+              ...item,
+              children: itemChildren
+            });
+          }
+          replacement = items == null ? block : {
+            ...block,
+            children: items
+          };
+          break;
+        }
+      case 'heading':
+      case 'paragraph':
+      case 'math':
+      case 'table':
+      case 'thematicBreak':
+      case 'image':
+      case 'extension':
+        replacement = block;
+        break;
+    }
+    if (next === undefined && replacement !== block) {
+      next = blocks.slice(0, index);
+    }
+    next?.push(replacement);
+  }
+  return next ?? blocks;
+}
+export function createMarkdownFenceTransform(options) {
+  if (!Array.isArray(options.languages) || options.languages.length === 0 || options.languages.some(language => typeof language !== 'string' || language.trim() === '')) {
+    throw new TypeError('Markdown fence languages must be non-empty strings');
+  }
+  if (new Set(options.languages).size !== options.languages.length) {
+    throw new TypeError('Markdown fence languages must be unique');
+  }
+  if (typeof options.createNode !== 'function') {
+    throw new TypeError('Markdown fence createNode must be a function');
+  }
+  const declaredLanguages = Object.freeze([...options.languages]);
+  const languages = new Set(declaredLanguages);
+  const sourceNeedles = Object.freeze(declaredLanguages.flatMap(language => [`\`\`\`${language}`, `~~~${language}`]));
+  const createNode = options.createNode;
+  const transform = (root, context) => {
+    const ownership = getMarkdownHelperOwnership(context);
+    if (ownership == null) {
+      throw new TypeError('Markdown fence transforms must run through createMarkdownPlugin');
+    }
+    const children = transformBlocks(root.children, languages, ownership.pluginName, ownership.hasRenderer, createNode, context.report);
+    return children === root.children ? root : {
+      ...root,
+      children
+    };
+  };
+
+  // Every node this helper inserts is validated above against the same
+  // rules Core applies to plugin-authored output — owned plugin name,
+  // registered renderer, representable frozen data, no authored provenance
+  // — and nothing else in the tree is touched. Core may therefore skip
+  // revalidating the whole document after it runs.
+  return markMarkdownTransformTrusted(markMarkdownTransformClaim(transform, source => sourceNeedles.some(needle => source.includes(needle))));
+}

package/dist/Markdown/plugins/sourceDecoration.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file sourceDecoration.ts
+ * @input Caller-supplied UTF-16 source ranges and non-semantic decoration payloads
+ * @output Immutable Markdown transforms that annotate Core-authored source-backed nodes
+ * @position Optional helper layer compiled onto the core transform protocol
+ */
+import type { MarkdownAstNodeBase } from '../ast';
+import { type MarkdownPluginData, type MarkdownTransform } from './protocol';
+/** One decoration recorded on an annotated node. */
+export interface MarkdownSourceDecoration {
+    /** Stable decoration name supplied by the helper's caller. */
+    readonly name: string;
+    /** Optional finite JSON-like payload copied from the matching range. */
+    readonly data?: MarkdownPluginData;
+}
+export interface MarkdownSourceDecorationRange {
+    /** Inclusive UTF-16 offset into the parsed source. */
+    readonly start: number;
+    /** Exclusive UTF-16 offset into the parsed source. */
+    readonly end: number;
+    /** Optional finite JSON-like payload recorded with this range. */
+    readonly data?: MarkdownPluginData;
+}
+export interface MarkdownSourceDecorationOptions {
+    /** Stable decoration name identifying every entry this helper records. */
+    readonly name: string;
+    /**
+     * Source ranges to decorate, as UTF-16 offsets into the same string the
+     * parser received. Order does not matter: entries are recorded in a fixed
+     * start, end, payload order so overlapping and duplicate ranges resolve the
+     * same way on every run. An empty list is a valid no-op.
+     */
+    readonly ranges: ReadonlyArray<MarkdownSourceDecorationRange>;
+}
+/**
+ * Compiles validated source ranges into an immutable transform that records
+ * non-semantic presentation metadata on the Core-authored nodes those ranges
+ * overlap.
+ *
+ * A node is decorated only when the parser authored its source position and
+ * the range overlaps its span, so the helper never changes AST meaning,
+ * rendered output, copyable text, accessible names, focus order, navigation,
+ * or source provenance. Core authors positions on top-level blocks, so a
+ * range decorates every block it touches, whatever order those blocks sit in
+ * after earlier transforms.
+ *
+ * Decorations describe settled source, so they appear on the final snapshot
+ * of a streaming document rather than on its partial chunks: a partial
+ * block's extent is still changing, and exposing decorations from it would
+ * let one appear and then vanish. Exposure is therefore monotone — never
+ * present, then absent.
+ *
+ * Decorations are stored in one Core-owned versioned envelope and read back
+ * with `getMarkdownSourceDecorations`; data the helper does not own is never
+ * merged into or overwritten.
+ *
+ * @example
+ * ```
+ * const reviewHits = createMarkdownPlugin({
+ *   name: 'review-hits',
+ *   apiVersion: 1,
+ *   transform: createMarkdownSourceDecoration({
+ *     name: 'review-hit',
+ *     ranges: [{start: 0, end: 12, data: {reviewer: 'ada'}}],
+ *   }),
+ * });
+ * ```
+ */
+export declare function createMarkdownSourceDecoration(options: MarkdownSourceDecorationOptions): MarkdownTransform<never>;
+/**
+ * Reads the decorations a source-decoration helper recorded on a node.
+ * Returns an empty list for undecorated nodes and for any value that is not
+ * a current Core-owned decoration envelope.
+ */
+export declare function getMarkdownSourceDecorations(node: MarkdownAstNodeBase): ReadonlyArray<MarkdownSourceDecoration>;
+//# sourceMappingURL=sourceDecoration.d.ts.map

package/dist/Markdown/plugins/sourceDecoration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceDecoration.d.ts","sourceRoot":"","sources":["../../../src/Markdown/plugins/sourceDecoration.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,mBAAmB,EAGpB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAYpB,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,MAAM,WAAW,6BAA6B;IAC5C,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,MAAM,WAAW,+BAA+B;IAC9C,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,6BAA6B,CAAC,CAAC;CAC/D;AAiXD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,iBAAiB,CAAC,KAAK,CAAC,CAwD1B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,GACxB,aAAa,CAAC,wBAAwB,CAAC,CAOzC"}