@aicayzer/inkkit 0.0.6 → 0.0.8

package/NOTICE

@@ -2,5 +2,28 @@ InkKit includes editor behavior and source from PadPad and Memos.
 Copyright (c) 2026 August Cayzer. Licensed under the MIT License.
 Sources: https://github.com/aicayzer/padpad and https://github.com/aicayzer/memos
 
-Milkdown and other runtime dependencies retain their own licenses. They are
-installed as dependencies rather than embedded in this package.
+The scoped table styles in src/style.css are adapted from prosemirror-tables.
+Source: https://github.com/ProseMirror/prosemirror-tables
+
+Copyright (C) 2015-2016 by Marijn Haverbeke <marijnh@gmail.com> and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Milkdown and other runtime dependencies retain their own licences. They are
+installed as dependencies.

package/README.md

@@ -1,6 +1,10 @@
 # InkKit
 
-InkKit is a TypeScript Markdown editor for offline web views and the web. It provides readable clipboard output, editable tables, optional host-managed images, and preservation of original Markdown and unsupported syntax.
+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.
+
+**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.
 
 ```sh
 npm install @aicayzer/inkkit
@@ -10,37 +14,35 @@ npm install @aicayzer/inkkit
 import { InkKitEditor } from '@aicayzer/inkkit'
 import '@aicayzer/inkkit/style.css'
 
-const editor = await InkKitEditor.mount(document.getElementById('editor')!, {
+const root = document.getElementById('editor')!
+const editor = await InkKitEditor.mount(root, {
   changed(text, generation) {
-    /* Notify the host. */
+    // Notify the host; capture a fresh snapshot when saving.
   },
   stateChanged(state) {
-    /* Update formatting controls. */
+    // Update the host's formatting controls.
   },
   openLink(href) {
-    /* Open through the host. */
+    // Open through the host.
   },
   copy(text) {
-    /* Write code-block text to the clipboard. */
+    // Write code-block text to the clipboard.
   },
 })
+
 editor.loadDocument({
   documentId: 'note',
   generation: 1,
   format: 'md',
-  text: '# Hello\n',
+  text: '# Hello\n\nStart writing.\n',
 })
 const snapshot = editor.snapshot(1)
 ```
 
-Markdown includes CommonMark, task lists, strikethrough, autolinks, GFM tables, editable footnotes and reference-style links, bounded callouts, highlights, author comments and offline Mermaid diagrams. Unsupported constructs remain literal Markdown. TXT mode treats all text literally. Images require a host adapter. RTF files remain outside the package scope.
-
-Table controls include complete row/column movement and explicit stable text or numeric sorting. Ordinary spreadsheet paste preserves cell boundaries, replaces selected cells and grows supported tables. Hosts call these operations through the public facade; each is undoable.
-
-`await editor.printableSnapshot(1)` returns a complete printable HTML document, print styles and portable image bytes. It excludes author comments, includes folded content and reports unavailable assets or a changed document. Client apps own Print/PDF commands, dialogs and file generation.
+InkKit runs on the web and in offline web views. Hosts use its public TypeScript facade and own toolbars, menus, persistence, clipboard bridges, Print/PDF actions and image storage. Images require an adapter; private references stay opaque. TXT stays literal. RTF files and richer media are outside current support.
 
-See [supported syntax](docs/supported-syntax.md), [the host API](docs/api.md), [preservation and clipboard behavior](docs/preservation.md), [development](docs/development.md), and [releases](docs/releasing.md).
+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.
 
-Delivery scope and release status are tracked in the [InkKit Project](https://github.com/users/aicayzer/projects/3) and [milestones](https://github.com/aicayzer/inkkit/milestones).
+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.
 
 MIT licensed. InkKit builds on the public PadPad and Memos editors; see [NOTICE](NOTICE).

package/dist/callouts.d.ts

@@ -1,3 +1,4 @@
+import type { EditorView } from '@milkdown/kit/prose/view';
 import type { Parent, RootContent } from 'mdast';
 interface Callout extends Parent {
     type: 'inkkitCallout';
@@ -17,6 +18,7 @@ declare module 'mdast' {
         inkkitCallout: Callout;
     }
 }
+export declare function revealCalloutAncestors(view: EditorView, position: number): void;
 export declare const remarkCalloutsPlugin: import("@milkdown/kit/utils").$Remark<"inkkitCallouts", unknown>;
 export declare const calloutSchema: import("@milkdown/kit/utils").$Node;
 export declare const calloutView: import("@milkdown/kit/utils").$Prose;

package/dist/callouts.js

@@ -1,8 +1,20 @@
 import { $node, $prose, $remark } from '@milkdown/kit/utils';
+import { editorLabels } from './labels.js';
 import { remarkCtx } from '@milkdown/kit/core';
 import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
 import { defaultHandlers } from 'mdast-util-to-markdown';
 const kinds = new Set(['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION']);
+export function revealCalloutAncestors(view, position) {
+    const node = view.domAtPos(position).node;
+    let element = node instanceof HTMLElement ? node : node.parentElement;
+    while (element && element !== view.dom) {
+        if (element.getAttribute('data-inkkit-folded') === 'true')
+            element
+                .querySelector(':scope > .inkkit-callout-header > [data-inkkit-callout-toggle]')
+                ?.click();
+        element = element.parentElement;
+    }
+}
 function plainHeader(processor, source) {
     const node = processor.parse(source).children[0];
     return node?.type === 'paragraph' &&
@@ -227,7 +239,7 @@ export const calloutSchema = $node('inkkit_callout', (ctx) => ({
         },
     },
 }));
-export const calloutView = $prose(() => new Plugin({
+export const calloutView = $prose((ctx) => new Plugin({
     key: new PluginKey('inkkitCalloutView'),
     props: {
         nodeViews: {
@@ -255,8 +267,10 @@ export const calloutView = $prose(() => new Plugin({
                     dom.setAttribute('data-inkkit-folded', String(folded));
                     button.hidden = !node.attrs.fold;
                     button.setAttribute('aria-expanded', String(!folded));
-                    button.setAttribute('aria-label', `${folded ? 'Expand' : 'Collapse'} ${title.textContent}`);
-                    button.textContent = folded ? 'Expand' : 'Collapse';
+                    button.setAttribute('aria-label', `${folded ? editorLabels(ctx).expandCallout : editorLabels(ctx).collapseCallout} ${title.textContent}`);
+                    button.textContent = folded
+                        ? editorLabels(ctx).expandCallout
+                        : editorLabels(ctx).collapseCallout;
                 };
                 const toggle = () => {
                     folded = !folded;

package/dist/decorations.js

@@ -1,15 +1,16 @@
 import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
 import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
 import { $prose } from '@milkdown/kit/utils';
+import { editorLabels } from './labels.js';
 const copyIcon = '<svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="5.5" y="5.5" width="8" height="8" rx="1.5"/><path d="M10.5 5.5v-2a1 1 0 0 0-1-1h-6a1 1 0 0 0-1 1v6a1 1 0 0 0 1 1h2"/></svg>';
 const doneIcon = '<svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 8.5l3 3 6-6.5"/></svg>';
 // The button reads the block's text when clicked, so the same widget can stay
 // mounted while the block is edited.
-function copyButton(onCopy) {
+function copyButton(onCopy, label) {
     const button = document.createElement('button');
     button.type = 'button';
     button.className = 'copy';
-    button.setAttribute('aria-label', 'Copy');
+    button.setAttribute('aria-label', label);
     button.innerHTML = copyIcon;
     button.addEventListener('mousedown', (event) => event.preventDefault());
     button.addEventListener('click', () => {
@@ -25,7 +26,7 @@ function copyButton(onCopy) {
     return button;
 }
 export function codeCopyPlugin(onCopy) {
-    return $prose(() => new Plugin({
+    return $prose((ctx) => new Plugin({
         key: new PluginKey('codeCopy'),
         props: {
             decorations(state) {
@@ -33,7 +34,7 @@ export function codeCopyPlugin(onCopy) {
                 state.doc.descendants((node, pos) => {
                     if (node.type.name !== 'code_block')
                         return true;
-                    widgets.push(Decoration.widget(pos + 1, () => copyButton(onCopy), {
+                    widgets.push(Decoration.widget(pos + 1, () => copyButton(onCopy, editorLabels(ctx).copyCode), {
                         side: -1,
                         key: 'copy',
                         ignoreSelection: true,
@@ -45,7 +46,7 @@ export function codeCopyPlugin(onCopy) {
         },
     }));
 }
-export const placeholderPlugin = $prose(() => new Plugin({
+export const placeholderPlugin = $prose((ctx) => new Plugin({
     key: new PluginKey('placeholder'),
     props: {
         decorations(state) {
@@ -58,7 +59,7 @@ export const placeholderPlugin = $prose(() => new Plugin({
             return DecorationSet.create(state.doc, [
                 Decoration.node(0, first.nodeSize, {
                     class: 'empty',
-                    'data-placeholder': 'Start typing…',
+                    'data-placeholder': editorLabels(ctx).placeholder,
                 }),
             ]);
         },

package/dist/dialect.js

@@ -1,8 +1,9 @@
 import { editorViewCtx, serializerCtx } from '@milkdown/kit/core';
-import { commonmark, hardbreakSchema, imageSchema, paragraphSchema, remarkInlineLinkPlugin, } from '@milkdown/kit/preset/commonmark';
+import { commonmark, docSchema, hardbreakSchema, imageSchema, paragraphSchema, remarkInlineLinkPlugin, } from '@milkdown/kit/preset/commonmark';
 import { extendListItemSchemaForTask, strikethroughAttr, strikethroughInputRule, strikethroughKeymap, strikethroughSchema, toggleStrikethroughCommand, wrapInTaskListInputRule, tableSchema, tableHeaderRowSchema, tableHeaderSchema, tableRowSchema, tableCellSchema, tableEditingPlugin, tableKeymap, goToNextTableCellCommand, goToPrevTableCellCommand, insertTableCommand, addRowBeforeCommand, addRowAfterCommand, addColBeforeCommand, addColAfterCommand, selectRowCommand, selectColCommand, deleteSelectedCellsCommand, setAlignCommand, exitTable, } from '@milkdown/kit/preset/gfm';
-import { $remark } from '@milkdown/kit/utils';
+import { $node, $remark } from '@milkdown/kit/utils';
 import { autolinkInputRule } from './autolink.js';
+import { sourceAttribute } from './source.js';
 import { normalizeTableAlignment, normalizeTableColumnAlignment, } from './table-alignment.js';
 import { preservingCodeBlocks, remarkCodeFences, fencedCodeHandler, } from './code-fences.js';
 import { literalBlock, createLiteralPreservation } from './literals.js';
@@ -274,6 +275,13 @@ export function createDialect(images) {
         // Protect unsupported inline HTML before the empty-line plugin consumes break nodes.
         createLiteralPreservation(images),
         commonmarkWithLiteralReferences,
+        $node('doc', () => ({
+            ...docSchema.schema,
+            attrs: {
+                ...docSchema.schema.attrs,
+                [sourceAttribute]: { default: null },
+            },
+        })),
         references,
         callouts,
         comments,

package/dist/editor.d.ts

@@ -1,5 +1,7 @@
+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 Heading } from './outline.js';
 export type Mark = 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'link';
 export type Block = {
     type: 'paragraph';
@@ -15,6 +17,7 @@ export type Block = {
 } | {
     type: 'taskList';
 };
+export type EditingMode = 'source' | 'formatted';
 export interface CaretState {
     marks: Mark[];
     block: Block;
@@ -22,11 +25,55 @@ export interface CaretState {
     quoted: boolean;
 }
 export type FormatCommand = 'heading' | 'paragraph' | 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'codeBlock' | 'quote' | 'bulletList' | 'orderedList' | 'taskList' | 'link';
-/** The bindings the app sets, by shortcut name; each runs a format command. */
+/** Host bindings by documented formatting, history or table shortcut name. */
 export type Keymap = Record<string, string[]>;
+export interface TextInputPreferences {
+    spellcheck?: boolean;
+    autocorrect?: boolean;
+    autocapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+}
+export interface EditorOptions {
+    images?: ImageAdapter;
+    editable?: boolean;
+    textInput?: TextInputPreferences;
+    labels?: Partial<EditorLabels>;
+    keymap?: Keymap;
+}
+export interface CommandState {
+    documentId: string;
+    generation: number;
+    revision: number;
+    format: 'md' | 'txt';
+    mode: EditingMode;
+    editable: boolean;
+    composing: boolean;
+    pending: boolean;
+    caret: CaretState;
+    table?: {
+        row: number;
+        column: number;
+        rows: number;
+        columns: number;
+    };
+    commands: {
+        undo: boolean;
+        redo: boolean;
+        insertText: boolean;
+        paste: boolean;
+        replace: boolean;
+        replaceSource: boolean;
+        insertImages: boolean;
+        insertPaths: boolean;
+        insertFootnote: boolean;
+        editReferenceDefinition: boolean;
+        format: Record<FormatCommand, boolean>;
+        table: Record<TableCommand, boolean>;
+    };
+}
 export interface EditorEvents {
     changed(markdown: string, generation: number): void;
     stateChanged(state: CaretState): void;
+    commandStateChanged?(state: CommandState): void;
     openLink(href: string): void;
     copy(text: string): void;
     error?(error: Error): void;
@@ -37,7 +84,6 @@ export declare class InkKitEditor {
     private readonly options;
     private editor;
     private lastMarkdown;
-    private baseline;
     private documentId;
     private formatType;
     private revision;
@@ -45,25 +91,57 @@ export declare class InkKitEditor {
     private operationSequence;
     private plainComposing;
     private plainSearch;
+    private literalMatch?;
+    private beforePlainInput?;
+    private mode;
+    private sourcePreservations;
+    private outlineEpoch;
     private ready;
     private destroyed;
     private preservation?;
     private pasteController;
     private plain;
     private root;
+    private ownsRootClass;
     private clickHandler?;
     private footnoteKeyHandler?;
     private copyHandler?;
     private originalSource;
     private generation;
+    private reportingSuppressed;
     private loading;
+    private writable;
+    private inputPreferences;
+    private policyEpoch;
+    private literalKeys;
+    private configuredKeys;
+    private readOnlyKeys;
     private changePlugin;
     private keys;
     private constructor();
     private context;
     private assertAlive;
     private assertCurrent;
-    private plainSource;
+    private assertMutation;
+    private get composing();
+    get editable(): boolean;
+    setEditable(editable: boolean): void;
+    setTextInputPreferences(preferences: TextInputPreferences): void;
+    private applyInputPolicy;
+    private publishCommandState;
+    commandState(expectedGeneration?: number): CommandState;
+    private canQuote;
+    private policyPlugin;
+    private get literalSurface();
+    get editingMode(): EditingMode;
+    private currentText;
+    setEditingMode(mode: EditingMode, expectedGeneration?: number): boolean;
+    private updateSurface;
+    replaceSource(text: string, expectedGeneration?: number): boolean;
+    private applySource;
+    undo(expectedGeneration?: number): boolean;
+    redo(expectedGeneration?: number): boolean;
+    private replaceLiteralSelection;
     snapshot(expectedGeneration?: number): DocumentSnapshot;
     printableSnapshot(expectedGeneration?: number): Promise<PrintableDocument>;
     clipboardSnapshot(all?: boolean): Promise<ClipboardOutput>;
@@ -73,13 +151,18 @@ export declare class InkKitEditor {
     table(command: TableCommand, options?: TableOptions): boolean;
     destroy(): Promise<void>;
     private keymapPlugin;
-    static mount(root: HTMLElement, events: EditorEvents, options?: {
-        images?: ImageAdapter;
-    }): Promise<InkKitEditor>;
+    private copySourceSelection;
+    static mount(root: HTMLElement, events: EditorEvents, options?: EditorOptions): Promise<InkKitEditor>;
     loadDocument(input: DocumentInput): void;
     reloadDocument(input: DocumentInput): void;
     private load;
-    find(text: string): void;
+    find(text: string, expectedGeneration?: number): void;
+    replace(search: string, replacement: string, expectedGeneration?: number): boolean;
+    replaceAll(search: string, replacement: string, expectedGeneration?: number): number;
+    private replaceMatches;
+    private outlineContext;
+    headings(expectedGeneration?: number): readonly Heading[];
+    navigateHeading(heading: Heading): boolean;
     /** Buffered native typing follows the same input rules as direct typing. */
     insertText(text: string, generation: number): boolean;
     /** Let existing keymaps handle buffered editing commands before native fallback. */