@aicayzer/inkkit 0.0.8 → 0.0.10

package/README.md

@@ -2,9 +2,9 @@
 
 InkKit is a reusable Markdown editor for simple writing tools and richer document apps. It provides formatted editing, source preservation, portable clipboard content and optional host-managed images, while your app controls its appearance, files and interface.
 
-Write in formatted or source mode with shared undo/redo. Edit tables, task lists, footnotes, reference links, highlights and callouts. Preview bounded Mermaid diagrams offline. Copy readable text and semantic HTML, explicitly copy Markdown source, or capture a complete printable document. Unsupported syntax remains editable literal Markdown.
+Write in formatted or source mode with shared undo/redo. Edit tables, task lists, footnotes, reference links, highlights and callouts. Preview bounded Mermaid diagrams offline. Copy readable text and semantic HTML, explicitly copy Markdown source, or capture a complete printable document. Native hosts can use scoped readable-text ranges and demand-driven geometry with their own search controls and viewport insets. Unsupported syntax remains editable literal Markdown.
 
-**Version status:** 0.0.7 is published. This branch documents the **unpublished 0.0.8 candidate**, adding read-only and text-input policies, command availability, scoped appearance, labels and shortcuts. Installing from npm currently gets the published release; the new controls require the candidate.
+Host controls, read-only and text-input policies, command availability, scoped appearance, labels and shortcuts are available from 0.0.8. Check the [releases](https://github.com/aicayzer/inkkit/releases) for published versions and verification evidence.
 
 ```sh
 npm install @aicayzer/inkkit
@@ -43,6 +43,8 @@ InkKit runs on the web and in offline web views. Hosts use its public TypeScript
 
 Start with the [feature guide](docs/supported-syntax.md) and [simple and rich integration examples](docs/integration.md). The [documentation index](docs/README.md) links to precise API, preservation, playground, verification and publication guidance.
 
-Scope and release status live in the [InkKit Project](https://github.com/users/aicayzer/projects/3) and [version milestones](https://github.com/aicayzer/inkkit/milestones). Planned search, viewport and media extensions are tracked there; they are not capabilities of this candidate.
+Scope and release status live in the [InkKit Project](https://github.com/users/aicayzer/projects/3) and [version milestones](https://github.com/aicayzer/inkkit/milestones). Optional media extensions are tracked there. Only documented, released features form the supported package contract.
 
 MIT licensed. InkKit builds on the public PadPad and Memos editors; see [NOTICE](NOTICE).
+
+Optional wiki links and a host-owned asynchronous file adapter support named/path images, audio, video, PDFs and file cards. Authored source and sizing are preserved; portable copy/print uses validated images or documented descriptive fallbacks. See [linked syntax](docs/supported-syntax.md#linked-syntax) and [adapter contracts](docs/api.md#optional-wiki-links-and-files).

package/dist/callouts.js

@@ -243,7 +243,7 @@ export const calloutView = $prose((ctx) => new Plugin({
     key: new PluginKey('inkkitCalloutView'),
     props: {
         nodeViews: {
-            inkkit_callout(node) {
+            inkkit_callout(node, view) {
                 const dom = document.createElement('blockquote');
                 dom.className = 'inkkit-callout';
                 dom.setAttribute('data-inkkit-callout', String(node.attrs.kind));
@@ -265,6 +265,7 @@ export const calloutView = $prose((ctx) => new Plugin({
                                 .toLowerCase()
                                 .replace(/^./, (letter) => letter.toUpperCase());
                     dom.setAttribute('data-inkkit-folded', String(folded));
+                    view.dom.dispatchEvent(new Event('inkkit-media-policy'));
                     button.hidden = !node.attrs.fold;
                     button.setAttribute('aria-expanded', String(!folded));
                     button.setAttribute('aria-label', `${folded ? editorLabels(ctx).expandCallout : editorLabels(ctx).collapseCallout} ${title.textContent}`);

package/dist/clipboard.d.ts

@@ -1,11 +1,11 @@
 import { type Fragment, type Schema } from '@milkdown/kit/prose/model';
-import type { ClipboardOutput, DocumentContext, ImageAdapter } from './types.js';
+import type { ClipboardOutput, DocumentContext, ImageAdapter, FileAdapter } from './types.js';
 export interface ClipboardContent {
     text: string;
     html: string;
 }
-export declare function clipboardText(content: Fragment, missingImages?: ReadonlySet<string>): string;
+export declare function clipboardText(content: Fragment, missingImages?: ReadonlySet<string>, fileDescriptions?: ReadonlyMap<object, string>): string;
 export declare function clipboardContent(content: Fragment, schema: Schema): ClipboardContent;
 export declare const visibleClipboard: import("@milkdown/kit/utils").$Prose;
 /** Export a frozen document fragment; presentation URLs never enter the clipboard. */
-export declare function portableClipboard(content: Fragment, schema: Schema, markdown: string, adapter: ImageAdapter | undefined, context: DocumentContext, completeDiagrams?: ReadonlySet<string>): Promise<ClipboardOutput>;
+export declare function portableClipboard(content: Fragment, schema: Schema, markdown: string, adapter: ImageAdapter | undefined, context: DocumentContext, completeDiagrams?: ReadonlySet<string>, files?: FileAdapter, signal?: AbortSignal): Promise<ClipboardOutput>;

package/dist/clipboard.js

@@ -3,30 +3,35 @@ import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
 import { $prose } from '@milkdown/kit/utils';
 import { shareableFragment } from './comments.js';
 import { diagramImage } from './mermaid.js';
+import { fileReference } from './linked-syntax.js';
+import { portableFile, portableFileImage } from './portable-files.js';
+import { withFileSignal } from './files.js';
 // Clipboard text is the visible document, not Markdown serialization: escaping
 // punctuation or trailing spaces here leaks source syntax into other apps.
-export function clipboardText(content, missingImages = new Set()) {
+export function clipboardText(content, missingImages = new Set(), fileDescriptions = new Map()) {
     content = shareableFragment(content);
     const blocks = [];
     content.forEach((node) => {
         if (node.type.name !== 'reference_definition')
-            blocks.push(nodeText(node, missingImages));
+            blocks.push(nodeText(node, missingImages, fileDescriptions));
     });
     const inline = content.firstChild?.isInline ?? false;
     return blocks.join(inline ? '' : '\n\n');
 }
-function nodeText(node, missingImages) {
+function nodeText(node, missingImages, fileDescriptions) {
+    if (node.type.name === 'inkkit_wiki_link')
+        return String(node.attrs.label || node.attrs.target || 'Link');
     if (node.type.name === 'inkkit_callout')
         return `${node.attrs.title ||
             String(node.attrs.kind)
                 .toLowerCase()
-                .replace(/^./, (letter) => letter.toUpperCase())}\n${clipboardText(node.content, missingImages)}`;
+                .replace(/^./, (letter) => letter.toUpperCase())}\n${clipboardText(node.content, missingImages, fileDescriptions)}`;
     if (node.type.name === 'reference_definition')
         return '';
     if (node.type.name === 'footnote_reference')
         return `[${node.attrs.label}]`;
     if (node.type.name === 'footnote_definition')
-        return `[${node.attrs.label}] ${clipboardText(node.content, missingImages)}`;
+        return `[${node.attrs.label}] ${clipboardText(node.content, missingImages, fileDescriptions)}`;
     if (node.isText)
         return node.text ?? '';
     if (node.type.name === 'hardbreak' || node.type.name === 'hard_break')
@@ -42,7 +47,7 @@ function nodeText(node, missingImages) {
             const indent = ' '.repeat(marker.length);
             const blocks = [];
             item.forEach((child, _childOffset, childIndex) => {
-                const text = nodeText(child, missingImages);
+                const text = nodeText(child, missingImages, fileDescriptions);
                 const nestedList = child.type.name === 'bullet_list' ||
                     child.type.name === 'ordered_list';
                 const lines = text.split('\n');
@@ -58,7 +63,10 @@ function nodeText(node, missingImages) {
         return items.join('\n');
     }
     if (node.type.name === 'image') {
-        const alt = String(node.attrs.alt ?? '').replace(/\|\d{1,5}$/, '') || 'Image';
+        const description = fileDescriptions.get(node.attrs);
+        if (description != null)
+            return description;
+        const alt = fileReference(node).label || 'Image';
         return missingImages.has(String(node.attrs.src ?? ''))
             ? `[${alt}: image unavailable]`
             : alt;
@@ -67,12 +75,12 @@ function nodeText(node, missingImages) {
         const rows = [];
         node.forEach((row) => {
             const cells = [];
-            row.forEach((cell) => cells.push(clipboardText(cell.content, missingImages)));
+            row.forEach((cell) => cells.push(clipboardText(cell.content, missingImages, fileDescriptions)));
             rows.push(cells.join('\t'));
         });
         return rows.join('\n');
     }
-    return clipboardText(node.content, missingImages);
+    return clipboardText(node.content, missingImages, fileDescriptions);
 }
 export function clipboardContent(content, schema) {
     content = shareableFragment(content);
@@ -82,6 +90,10 @@ export function clipboardContent(content, schema) {
     // fetches authored references or temporary presentation URLs.
     const safe = new DOMSerializer({
         ...serializer.nodes,
+        inkkit_wiki_link: (node) => [
+            'span',
+            String(node.attrs.label || node.attrs.target || 'Link'),
+        ],
         image: (node) => [
             'img',
             {
@@ -111,31 +123,53 @@ export const visibleClipboard = $prose(() => new Plugin({
     },
 }));
 /** Export a frozen document fragment; presentation URLs never enter the clipboard. */
-export async function portableClipboard(content, schema, markdown, adapter, context, completeDiagrams) {
+export async function portableClipboard(content, schema, markdown, adapter, context, completeDiagrams, files, signal = new AbortController().signal) {
+    signal.throwIfAborted();
     content = shareableFragment(content);
     const base = clipboardContent(content, schema);
     const container = document.createElement('div');
     container.innerHTML = base.html;
     const images = [];
     const references = [];
+    const fileDescriptions = new Map();
     content.descendants((node) => {
         if (node.type.name === 'image')
-            references.push(String(node.attrs.src ?? ''));
+            references.push(node);
     });
     const captured = [...container.querySelectorAll('img')].map((element, index) => {
-        const reference = references[index] ?? '';
-        const alt = element.getAttribute('alt')?.replace(/\|\d{1,5}$/, '') || 'Image';
+        const node = references[index];
+        const reference = String(node?.attrs.src ?? '');
+        const { label: authoredAlt, width } = fileReference(node);
+        const alt = authoredAlt || 'Image';
+        if (width != null && width > 0)
+            element.setAttribute('width', String(Math.min(4096, width)));
         element.removeAttribute('src');
         element.removeAttribute('srcset');
-        return { element, reference, alt };
+        return { element, node, reference, alt };
     });
-    await Promise.all(captured.map(async ({ element, reference, alt }, index) => {
+    await Promise.all(captured.map(async ({ element, node, reference, alt }, index) => {
+        let label = alt;
         element.setAttribute('data-inkkit-image-slot', String(index));
         element.setAttribute('data-inkkit-authored-image-slot', String(index));
         try {
-            if (!adapter)
+            const file = files
+                ? await portableFile(node, files, context, signal)
+                : undefined;
+            if (file && file.presentation.kind !== 'image') {
+                const fallback = document.createElement('span');
+                fallback.textContent = file.description;
+                element.replaceWith(fallback);
+                fileDescriptions.set(node.attrs, file.description);
+                return;
+            }
+            label = file?.label || alt;
+            if (!files && !adapter)
                 throw new Error('The image is unavailable.');
-            const image = await adapter.exportImage(reference, { ...context });
+            const input = file
+                ? await portableFileImage(file, files, adapter, context, signal)
+                : await withFileSignal(adapter.exportImage(reference, { ...context }), signal);
+            signal.throwIfAborted();
+            const image = { ...input, bytes: new Uint8Array(input.bytes) };
             if (!/^image\/(png|jpeg|gif|webp|avif|bmp|tiff)$/i.test(image.mimeType))
                 throw new Error('The image format cannot be exported.');
             let binary = '';
@@ -143,15 +177,18 @@ export async function portableClipboard(content, schema, markdown, adapter, cont
                 binary += String.fromCharCode(byte);
             const portable = `data:${image.mimeType};base64,${btoa(binary)}`;
             element.setAttribute('src', portable);
-            element.setAttribute('alt', alt);
-            images[index] = { reference, alt, image };
+            element.setAttribute('alt', label);
+            fileDescriptions.set(node.attrs, label);
+            images[index] = { reference, alt: label, image };
         }
         catch (error) {
+            signal.throwIfAborted();
             const message = error instanceof Error ? error.message : 'The image is unavailable.';
             const warning = document.createElement('span');
-            warning.textContent = `[${alt}: image unavailable]`;
+            warning.textContent = `[${label}: image unavailable]`;
             element.replaceWith(warning);
-            images[index] = { reference, alt, error: message };
+            fileDescriptions.set(node.attrs, warning.textContent);
+            images[index] = { reference, alt: label, error: message };
         }
     }));
     const diagrams = [];
@@ -162,7 +199,7 @@ export async function portableClipboard(content, schema, markdown, adapter, cont
         const result = { source };
         diagrams.push(result);
         try {
-            const image = await diagramImage(source);
+            const image = await withFileSignal(diagramImage(source), signal);
             let binary = '';
             for (const byte of image.bytes)
                 binary += String.fromCharCode(byte);
@@ -179,6 +216,7 @@ export async function portableClipboard(content, schema, markdown, adapter, cont
             result.image = image;
         }
         catch (error) {
+            signal.throwIfAborted();
             result.error =
                 error instanceof Error
                     ? error.message
@@ -211,12 +249,13 @@ export async function portableClipboard(content, schema, markdown, adapter, cont
                     /^javascript:/i.test(attribute.value)))
                 element.removeAttribute(attribute.name);
     }
-    const missing = new Set(images.filter((image) => image.error).map((image) => image.reference));
+    const missing = new Set(images.filter((image) => image?.error).map((image) => image.reference));
+    signal.throwIfAborted();
     return {
-        text: clipboardText(content, missing),
+        text: clipboardText(content, missing, fileDescriptions),
         html: container.innerHTML,
         markdown,
-        images: [...orderedImages, ...images.filter((image) => image.error)],
+        images: [...orderedImages, ...images.filter((image) => image?.error)],
         diagrams,
     };
 }

package/dist/dialect.d.ts

@@ -3,7 +3,7 @@ import type { Node as ProseNode } from '@milkdown/kit/prose/model';
 import { type Options as StringifyOptions } from 'mdast-util-to-markdown';
 export declare const remarkDialectPlugin: import("@milkdown/kit/utils").$Remark<"remarkDialect", unknown>;
 export declare const tables: MilkdownPlugin[];
-export declare function createDialect(images: boolean): MilkdownPlugin[];
+export declare function createDialect(images: boolean, wikiLinks?: boolean, files?: boolean): MilkdownPlugin[];
 export declare const dialect: MilkdownPlugin[];
 export declare const stringifyOptions: StringifyOptions;
 export declare function serialize(ctx: Ctx, doc?: ProseNode): string;

package/dist/dialect.js

@@ -4,6 +4,7 @@ import { extendListItemSchemaForTask, strikethroughAttr, strikethroughInputRule,
 import { $node, $remark } from '@milkdown/kit/utils';
 import { autolinkInputRule } from './autolink.js';
 import { sourceAttribute } from './source.js';
+import { linkedSyntax, wikiLinkSchema, namedFileMarkdown, fileReference, } from './linked-syntax.js';
 import { normalizeTableAlignment, normalizeTableColumnAlignment, } from './table-alignment.js';
 import { preservingCodeBlocks, remarkCodeFences, fencedCodeHandler, } from './code-fences.js';
 import { literalBlock, createLiteralPreservation } from './literals.js';
@@ -178,6 +179,14 @@ const normalizedImages = imageSchema.extendSchema((base) => (ctx) => {
     const schema = base(ctx);
     return {
         ...schema,
+        attrs: {
+            ...schema.attrs,
+            inkkitFileRaw: { default: null },
+            inkkitFileTarget: { default: null },
+            inkkitFileFragment: { default: null },
+            inkkitFileWidth: { default: null },
+            inkkitFileInTable: { default: false },
+        },
         parseDOM: [
             {
                 tag: 'img[src]',
@@ -197,6 +206,29 @@ const normalizedImages = imageSchema.extendSchema((base) => (ctx) => {
                     src: String(node.url ?? ''),
                     alt: String(node.alt ?? ''),
                     title: String(node.title ?? ''),
+                    inkkitFileRaw: node.inkkitFileRaw ?? null,
+                    inkkitFileTarget: node.inkkitFileTarget ?? null,
+                    inkkitFileFragment: node.inkkitFileFragment ?? null,
+                    inkkitFileWidth: node.inkkitFileWidth ?? null,
+                    inkkitFileInTable: node.inkkitFileInTable ?? false,
+                });
+            },
+        },
+        toMarkdown: {
+            ...schema.toMarkdown,
+            runner(state, node) {
+                const raw = namedFileMarkdown(node, Boolean(node.attrs.inkkitFileInTable));
+                if (raw == null)
+                    return schema.toMarkdown.runner(state, node);
+                state.addNode('image', undefined, undefined, {
+                    url: node.attrs.src,
+                    alt: node.attrs.alt,
+                    title: node.attrs.title || null,
+                    inkkitFileRaw: raw,
+                    inkkitFileTarget: node.attrs.inkkitFileTarget,
+                    inkkitFileFragment: node.attrs.inkkitFileFragment,
+                    inkkitFileWidth: fileReference(node).width ?? null,
+                    inkkitFileInTable: node.attrs.inkkitFileInTable,
                 });
             },
         },
@@ -266,14 +298,15 @@ export const tables = [
     setAlignCommand,
     exitTable,
 ].flat();
-export function createDialect(images) {
+export function createDialect(images, wikiLinks = false, files = false) {
     return [
         remarkCodeFences,
         remarkReferencesPlugin,
         remarkCalloutsPlugin,
         remarkCommentsPlugin,
+        wikiLinks || files ? linkedSyntax(wikiLinks, files) : [],
         // Protect unsupported inline HTML before the empty-line plugin consumes break nodes.
-        createLiteralPreservation(images),
+        createLiteralPreservation(images || files),
         commonmarkWithLiteralReferences,
         $node('doc', () => ({
             ...docSchema.schema,
@@ -283,6 +316,7 @@ export function createDialect(images) {
             },
         })),
         references,
+        wikiLinks ? wikiLinkSchema : [],
         callouts,
         comments,
         inlineHighlight,

package/dist/editor.d.ts

@@ -1,6 +1,6 @@
 import { type EditorLabels } from './labels.js';
 import { type TableCommand, type TableOptions } from './tables.js';
-import { type DocumentInput, type DocumentSnapshot, type ImageAdapter, type ClipboardInput, type ClipboardOutput, type PrintableDocument } from './types.js';
+import { type DocumentInput, type DocumentSnapshot, type ImageAdapter, type FileAdapter, type WikiLinkAdapter, type ClipboardInput, type ClipboardOutput, type PrintableDocument, type TextRange, type ReadableTextSnapshot, type TextRect, type ViewportOptions, type ViewportSnapshot } from './types.js';
 import { type Heading } from './outline.js';
 export type Mark = 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'link';
 export type Block = {
@@ -34,6 +34,8 @@ export interface TextInputPreferences {
 }
 export interface EditorOptions {
     images?: ImageAdapter;
+    files?: FileAdapter;
+    wikiLinks?: WikiLinkAdapter;
     editable?: boolean;
     textInput?: TextInputPreferences;
     labels?: Partial<EditorLabels>;
@@ -89,6 +91,7 @@ export declare class InkKitEditor {
     private revision;
     private documentEpoch;
     private operationSequence;
+    private exportControllers;
     private plainComposing;
     private plainSearch;
     private literalMatch?;
@@ -110,6 +113,10 @@ export declare class InkKitEditor {
     private generation;
     private reportingSuppressed;
     private loading;
+    private readonly textIdentity;
+    private textScope?;
+    private viewportContainer?;
+    private viewportInsets;
     private writable;
     private inputPreferences;
     private policyEpoch;
@@ -120,6 +127,9 @@ export declare class InkKitEditor {
     private keys;
     private constructor();
     private context;
+    private cancelExports;
+    private exportContent;
+    private mediaPolicy;
     private assertAlive;
     private assertCurrent;
     private assertMutation;
@@ -155,6 +165,22 @@ export declare class InkKitEditor {
     static mount(root: HTMLElement, events: EditorEvents, options?: EditorOptions): Promise<InkKitEditor>;
     loadDocument(input: DocumentInput): void;
     reloadDocument(input: DocumentInput): void;
+    setViewport(options: ViewportOptions): void;
+    viewport(): ViewportSnapshot;
+    private readableScope;
+    textSnapshot(expectedGeneration?: number): ReadableTextSnapshot;
+    private validateTextRange;
+    selectTextRange(range: TextRange, options?: {
+        focus?: boolean;
+        reveal?: boolean;
+    }): void;
+    replaceTextRange(range: TextRange, text: string): boolean;
+    textRangeRects(range: TextRange): readonly TextRect[];
+    visibleTextRanges(snapshotId: string): readonly TextRange[];
+    revealTextRange(range: TextRange): void;
+    private revealRects;
+    private revealCurrentSelection;
+    private revealLiteralSelection;
     private load;
     find(text: string, expectedGeneration?: number): void;
     replace(search: string, replacement: string, expectedGeneration?: number): boolean;