arcane-os 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.37.0
+
+- Add opt-in `markdown-editor` fit layout and preview following through
+  `configure({fit:true, followPreview:true})` or `data-fit` and
+  `data-follow-preview`. Both options default to false. Fit mode keeps the
+  title, formatting controls, input, preview and save/status actions visible
+  in a bounded responsive layout with independent input and preview scrolling.
+- Follow body edits and formatting at their rendered Markdown block without
+  moving the input or containing page. Title edits and manual preview reading
+  preserve the reader's position. Expose named CSS parts for application styling.
+- Add `new MD(raw,{sourceMap:true})` with ordered original UTF-16 source ranges
+  and rendered comment anchors. Preserve complete raw content, ordinary default
+  rendering, formatting, save payloads, cancellation and cleanup. No saved-data
+  migration or model/provider/default changes.
+
+## 0.36.1
+
+- Infer ordinary audio MIME types from mp3, wav, ogg, oga, opus, aac, m4a,
+  flac and weba filenames when stored files have no supplied MIME metadata.
+  Native file previews can select audio controls without decoding audio as text.
+- Preserve supplied MIME types, existing non-audio classification, the original
+  file and complete payload. An untyped webm remains ambiguous and retains its
+  ordinary download behavior. No stored files are rewritten.
+
 ## 0.36.0
 
 - Add optional continuous microphone capture to `voice-transcription` through

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.36.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.37.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/inventory/runtime-components.json

@@ -515,7 +515,7 @@
     {
       "file": "runtime/arcane/components/markdown-editor.html",
       "name": "markdown-editor.html",
-      "purpose": "Configurable Markdown authoring, toolbar, preview, title, and save surface.",
+      "purpose": "Configurable Markdown authoring, toolbar, preview, plain-text title, and save surface with optional bounded input/preview panes and edit-position following.",
       "methods": [
         "configure()",
         "focus()",
@@ -535,7 +535,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Editor values normalized; injected save result mixed"
+      "normalization": "Editor values and optional presentation behavior normalized; injected save result mixed. fit and followPreview default false, preserve omitted prior configuration, and accept explicit false resets; data-fit and data-follow-preview select the initial options. Fit requires an application-bounded host and provides independent input/preview scrolling in roomy columns or narrow stacked panes without changing the application shell. Following responds to body typing/format edits, leaves manual preview scrolling independent until the next edit, and does not treat title edits or programmatic value replacement as follow requests. Public parts editor/title/toolbar/input/preview/actions/status/save-action allow application styling while the title stays native plain text. Existing controls, complete save payload, save cancellation, and destruction behavior remain."
     },
     {
       "file": "runtime/arcane/components/media-embed.html",

package/docs/reference/inventory/runtime-modules.json

@@ -417,7 +417,7 @@
       "availability": "Cross-host with an injected event constructor outside DOM hosts",
       "protocol": "In-process only",
       "normalization": "Fully normalized labels, rows, definitions, visibility, formats, editor and voice options, plus capability-neutral STT activation intent and presentation state. Complete finite progress measures remain visible, including fractional and over-total values.",
-      "surface": "Constant sets plus normalization, complete finite-progress formatting, and explicit STT activation helpers. normalizeVoiceOptions preserves manual capture and standard controls by default and accepts continuous capture timing/activity options, simple controls, showComplete, and retry/cancel labels."
+      "surface": "Constant sets plus normalization, complete finite-progress formatting, and explicit STT activation helpers. normalizeVoiceOptions preserves manual capture and standard controls by default and accepts continuous capture timing/activity options, simple controls, showComplete, and retry/cancel labels. normalizeMarkdownOptions adds fit and followPreview strict booleans default false, retains omitted prior values, and accepts explicit false resets without changing existing editor options."
     },
     {
       "file": "runtime/arcane/modules/ConfiguredAIChatSession.js",
@@ -885,11 +885,11 @@
       "exports": [
         "default"
       ],
-      "summary": "Renders complete Markdown with Marked and exposes the complete rendered markup.",
+      "summary": "Renders complete Markdown with Marked and optionally maps source blocks to rendered comment anchors.",
       "availability": "Browser / native WebView",
       "protocol": "Marked",
-      "normalization": "Complete raw and rendered Marked values; parse errors remain vendor-native.",
-      "surface": "default `MD`; `raw`, `rendered`, `safeRendered`, `append()`."
+      "normalization": "Complete raw and rendered Marked values; parse errors remain vendor-native. Opt-in source mapping preserves original UTF-16 offsets and adds only comment anchors to complete rendered output. Lists, quotes, and tables map at top-level block granularity; invisible source or unavailable parsed anchors use the consumer's nearest available block behavior. Mapping is rebuilt on raw replacement and append, without persistence or viewport movement.",
+      "surface": "default MD; new MD(raw,{sourceMap:true}) enables ordered sourceMap records {start,end,marker,type}, with inclusive start/exclusive end in original UTF-16 source positions and marker equal to generated comment data. Locate anchors with a comment TreeWalker, not a CSS selector. Markers are opaque and may change after edits. sourceMap exposes the current mutable array, replaced after each successful render. raw, rendered, safeRendered, and append() remain; default sourceMap is empty and ordinary output is unchanged. Rendering and getters are DOM-independent."
     },
     {
       "file": "runtime/arcane/modules/MemoryRecords.js",

package/docs/reference/runtime-components.md

@@ -77,7 +77,7 @@ appropriate.
 | [`integration-settings.html`](#integration-settingshtml) | Edits non-secret communication service configuration and service actions. | `configure()`<br>`getValues()`<br>`setStatus()`<br>`destroy()` | `integration-settings-ready`<br>`integration-settings-save`<br>`integration-settings-close`<br>`integration-action` | Normalized non-secret values |
 | [`local-ai-status.html`](#local-ai-statushtml) | Presents local-AI standby, failure, recovery, guidance, retry, and dismissal states. | `configure()`<br>`begin()`<br>`present()`<br>`destroy()`<br>`hidden` | `local-ai-status-ready`<br>`local-ai-status-dismissed`<br>`local-ai-retry` | Fully normalized LocalAIReadiness report |
 | [`markdown-document.html`](#markdown-documenthtml) | Renders and navigates a complete Markdown document with focusable fragments. | `configure()`<br>`load()`<br>`render()`<br>`clear()`<br>`fail()`<br>`focus()`<br>`focusFragment()`<br>`destroy()` | `markdown-document-ready`<br>`markdown-document-state`<br>`markdown-document-loading`<br>`markdown-document-rendered`<br>`markdown-document-empty`<br>`markdown-document-error`<br>`markdown-document-navigate` | Complete Markdown/state normalized; malformed input and Marked/DOM failures remain visible |
-| [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring, toolbar, preview, title, and save surface. | `configure()`<br>`focus()`<br>`clear()`<br>`saveEntry()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values normalized; injected save result mixed |
+| [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring with optional bounded input/preview panes and edit-position following. | `configure()`<br>`focus()`<br>`clear()`<br>`saveEntry()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values, opt-in fit layout, and preview following normalized; injected save result mixed |
 | [`media-embed.html`](#media-embedhtml) | Loads a parsed YouTube video or playlist embed with ordinary hosting by default, optional privacy enhancement, and an external-platform action. | `configure()`<br>`load()`<br>`destroy()` | `media-embed-ready`<br>`media-load`<br>`media-error`<br>`media-open-platform` | URL/error normalized; iframe/platform behavior native |
 | [`modal.html`](#modalhtml) | Generic modal with population, configurable user dismissal, actions, and concurrent task execution. | `configure()`<br>`populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()`<br>`running`<br>`opened` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
 | [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
@@ -1021,11 +1021,56 @@ subject to the bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Overview
 
-Configurable Markdown authoring, toolbar, preview, title, and save surface.
+Configurable Markdown authoring, toolbar, preview, plain-text title, and save
+surface. The default editor retains its growing stacked layout and existing
+controls. Optional fit mode keeps the Markdown input and rendered preview
+inside an application-supplied bounded area.
 
 ### Public surface
 
-Methods/properties: `configure()`, `focus()`, `clear()`, `saveEntry()`, `destroy()`.
+Methods/properties: `configure()`, `focus()`, `clear()`, `saveEntry()`,
+`destroy()`, `value`, `entryTitle`, `options`.
+
+`configure({fit:true,followPreview:true})` opts into the two independent
+behaviors. Both options default to `false`; omitted options retain their
+previous values during reconfiguration, and explicit `false` disables either.
+Initial markup can use `data-fit="true"` and `data-follow-preview="true"`.
+
+`fit:true` fills the host's available height. The application must supply a
+bounded host height and allow its enclosing flex/grid item to shrink, for
+example with `min-height:0`. Input and preview have independent scroll areas:
+two columns when room permits and two bounded stacked panes on narrow widths.
+Title, toolbar, status, and save remain outside those scrolling panes. Hiding
+the preview leaves the input the available pane space. Fit mode does not
+change the application's fixed shell or scroll the page.
+
+`followPreview:true` follows the Markdown body's active edit position after
+typing or applying a toolbar format. It scrolls the preview only as needed
+to bring a short corresponding block into view; a block taller than the pane
+uses the caret's approximate fraction within that block. Users can scroll the
+preview independently, and rerendering retains that reading position; the next
+body edit may reposition it. Title edits,
+programmatic value replacement, and ordinary preview scrolling do not request
+edit-position following. Moving the selection alone does not trigger following,
+and following never scrolls the input pane or containing page. The title
+remains a native plain-text input.
+Following uses the shared [Markdown block mapping](runtime-modules.md#mdjs);
+lists, quotes, and tables follow their block, while invisible source positions
+use a nearby available rendered block rather than exact glyph geometry.
+
+Public CSS parts are `editor`, `title`, `toolbar`, `input`, `preview`,
+`actions`, `status`, and `save-action`. Applications can make the title
+borderless and compact through `::part(title)` while retaining its native
+editing behavior and visible keyboard focus. These parts are styling hooks,
+not slots or replacement controls.
+
+Existing `showTitle`, `showToolbar`, `showSave`, `showPreview`, `readOnly`,
+`clearOnSave`, labels, formats, and callbacks keep their behavior. `onSave`
+or the host's `save` receives complete `{title,markdown}` plus a second
+`{signal,operationId}` context; layout and following add no fields to the
+saved content. Edits, replacement, clear, and destruction retain the existing
+save cancellation and late-result suppression. Destruction also cancels the
+pending preview frame.
 
 Events: `markdown-editor-ready`, `markdown-editor-change`, `markdown-editor-saved`.
 
@@ -1033,7 +1078,10 @@ Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`ComponentContracts.js
 
 ### Availability and normalization
 
-**Browser and supported native WebViews.** Editor values normalized; injected save result mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
+**Browser and supported native WebViews.** Editor values, opt-in fit layout,
+and preview following are normalized; the injected save result remains
+application-owned. HTMLImport + DOM; native methods remain subject to the
+bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Example
 
@@ -1044,6 +1092,28 @@ Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`ComponentContracts.js
 </html-import>
 ```
 
+For a bounded editor, choose the height in the application and style only the
+public title part:
+
+```html
+<style>
+  #field-notes { display:block; height:32rem; min-height:0; }
+  #field-notes::part(title) {
+    border:0;
+    border-radius:0;
+    background:transparent;
+    padding:.35em 0;
+  }
+</style>
+<html-import
+  id="field-notes"
+  href="/arcane/components/markdown-editor.html"
+  data-fit="true"
+  data-follow-preview="true"
+  data-title-placeholder="Dragon field notes">
+</html-import>
+```
+
 ## media-embed.html
 
 ### Overview

package/docs/reference/runtime-modules.md

@@ -98,7 +98,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`MailTransport.mjs`](#mailtransportmjs) | esm | Sends one complete mail report to a normalized HTTP(S) endpoint. | Browser/server with fetch + cloud | Normalized endpoint and transport errors; remote detail preserved. |
 | [`MarkdownSpeech.js`](#markdownspeechjs) | esm | Removes repeated Markdown formatting marks from streamed narration. | Cross-host | Speech-only filtering; single marks and ordinary punctuation remain literal. |
 | [`Marked.min.js`](#markedminjs) | esm | Vendored Marked 18.0.5 Markdown lexer, parser, renderer, extension, and walk-token API. | Cross-host vendor module | Vendor-native Marked contract. |
-| [`MD.js`](#mdjs) | esm | Renders complete Markdown with Marked and exposes the complete rendered markup. | Browser / native WebView | Complete raw and rendered Marked values; parse errors vendor-native. |
+| [`MD.js`](#mdjs) | esm | Renders complete Markdown with Marked and optionally maps source blocks to rendered comment anchors. | Browser / native WebView | Complete raw and rendered Marked values; opt-in original-source offsets; parse errors vendor-native. |
 | [`MemoryRecords.js`](#memoryrecordsjs) | esm | Normalizes memory content and detects meaningful stored memory. | Cross-host | Fully normalized string/boolean results. |
 | [`MessageAdvisory.js`](#messageadvisoryjs) | esm | Normalizes message content advisories and contains per-message inspection failures. | Cross-host | Normalized advisory records; inspector failures converted to unavailable results. |
 | [`ModelDefinition.js`](#modeldefinitionjs) | esm | Parses the deterministic packaged Modelfile subset and extracts the SYSTEM prompt. | Cross-host | Complete mutable definition with coded malformed-input errors. |
@@ -1647,6 +1647,14 @@ the shared voice component. Positive quiet/chunk durations and nonnegative
 pre-roll/activity values must be finite. Complete callback payloads remain
 owned by the component and application.
 
+`normalizeMarkdownOptions(input,previous)` adds strict opt-in `fit` and
+`followPreview` booleans, both defaulting to `false`. Omitted fields preserve
+the corresponding previous value; explicit `false` disables the option.
+Existing Markdown labels, formats, visibility, read-only state, save behavior,
+callbacks, complete initial Markdown, and plain initial title remain intact.
+The shared editor consumes these options for bounded responsive panes and
+body-edit preview following; the normalizer itself performs no DOM work.
+
 `createSTTActivationController({host,button,progress=null,onChange,EventClass=CustomEvent})`
 consumes only normalized
 [`AIRuntimeState`](#airuntimestatejs) `stt` role records. Its mutable controller
@@ -2759,25 +2767,66 @@ console.log(Object.keys(module));
 ### Overview
 
 Renders complete Markdown with Marked and exposes the same complete rendered
-markup through `rendered` and `safeRendered`.
-
-### Public surface
-
-default `MD`; `raw`, `rendered`, `safeRendered`, `append()`.
+markup through `rendered` and `safeRendered`. Optional source mapping lets a
+consumer locate rendered blocks without adding visible wrappers or changing
+the authored Markdown.
+
+### Public surface
+
+Default `MD`; `raw`, `rendered`, `safeRendered`, `sourceMap`, `append()`.
+
+`new MD(raw,{sourceMap:true})` enables block mapping. The `sourceMap` getter
+returns ordered `{start,end,marker,type}` records. `start` is inclusive and
+`end` is exclusive, measured in UTF-16 positions in the exact original `raw`
+string, matching native textarea selection offsets. `marker` is the complete
+data of a generated HTML comment, not a CSS selector. A consumer can locate
+it after rendering with `document.createTreeWalker(root,NodeFilter.SHOW_COMMENT)`.
+The generated marker prefix is chosen so it does not collide with authored
+source comments. Marker values are opaque and may change after an edit.
+The getter exposes the current mutable array; each successful render replaces
+it with a new array, so a previously retained array describes the prior render.
+
+In this opt-in mode, `rendered` and `safeRendered` contain the complete rendered
+Markdown plus comment anchors; no element wrappers or attributes are added.
+Lists, block quotes, and tables map at their top-level block rather than to
+individual characters. Blank space and definitions have no visible block;
+raw HTML can also absorb a comment during DOM parsing. A consumer follows the
+nearest available rendered block in those cases. This is block-position
+mapping, not exact rendered glyph or caret geometry.
+
+Assigning `raw` or calling `append(string)` rebuilds both the complete rendered
+result and its current mapping. Without `sourceMap:true`, `sourceMap` is empty
+and the ordinary rendered output is unchanged. Existing raw content, link
+behavior, no-op `rendered` setter, and complete `append()` result remain.
 
 Exact exports: `default`.
 
 ### Availability and normalization
 
 **Browser / native WebView.** Raw Marked behavior is preserved; parse errors are
-vendor-native. Transport: Marked. [Deep protocol details](protocols.md).
+vendor-native. Rendering and the getters are DOM-independent. DOM lookup and
+scrolling belong to the consuming component;
+mapping performs no persistence or viewport movement. Transport: Marked.
+[Deep protocol details](protocols.md).
 
 ### Example
 
 ```javascript
-import * as module from '/arcane/modules/MD.js';
+import MD from '/arcane/modules/MD.js';
 
-console.log(Object.keys(module));
+const notes=new MD('# Dragon field notes\n\nThe library dragon ate the index.',{
+    sourceMap:true
+});
+const preview=document.querySelector('#preview');
+preview.innerHTML=notes.safeRendered;
+const comments=document.createTreeWalker(preview,NodeFilter.SHOW_COMMENT);
+const firstBlock=notes.sourceMap[0];
+while(comments.nextNode()){
+    if(comments.currentNode.data===firstBlock.marker){
+        console.log(firstBlock,comments.currentNode.nextSibling);
+        break;
+    }
+}
 ```
 
 ## MemoryRecords.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -86,7 +86,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/components/markdown-editor.html

@@ -4,6 +4,12 @@
         display:block;
     }
 
+    :host([data-fit="true"]){
+        min-width:0;
+        min-height:0;
+        container:arcane-markdown-editor / inline-size;
+    }
+
     .markdown-editor{
         display:grid;
         gap:.75em;
@@ -57,19 +63,62 @@
         margin-right:auto;
     }
 
+    .markdown-editor.fit{
+        height:100%;
+        min-height:0;
+        min-width:0;
+        grid-template-columns:minmax(0,1fr) minmax(0,1fr);
+        grid-template-rows:auto auto minmax(0,1fr) auto;
+        grid-template-areas:"title title" "toolbar toolbar" "input preview" "actions actions";
+    }
+
+    .fit .entry-title{grid-area:title;}
+    .fit .toolbar{grid-area:toolbar;}
+    .fit .entry-markdown{grid-area:input;}
+    .fit .preview{grid-area:preview;}
+    .fit .actions{grid-area:actions;}
+
+    .fit .entry-markdown,
+    .fit .preview{
+        box-sizing:border-box;
+        min-width:0;
+        min-height:0;
+        height:100%;
+        overflow:auto;
+        overscroll-behavior:contain;
+    }
+
+    .fit .entry-markdown{resize:none;}
+    .fit .preview{overflow-wrap:anywhere;}
+    .fit .preview img{max-width:100%;height:auto;}
+    .fit.without-preview{grid-template-areas:"title title" "toolbar toolbar" "input input" "actions actions";}
+
+    @container arcane-markdown-editor (max-width:44rem){
+        .markdown-editor.fit{
+            grid-template-columns:minmax(0,1fr);
+            grid-template-rows:auto auto minmax(0,1fr) minmax(0,1fr) auto;
+            grid-template-areas:"title" "toolbar" "input" "preview" "actions";
+        }
+
+        .markdown-editor.fit.without-preview{
+            grid-template-rows:auto auto minmax(0,1fr) auto;
+            grid-template-areas:"title" "toolbar" "input" "actions";
+        }
+    }
+
     .hidden{
         display:none;
     }
 </style>
 
-<section class="markdown-editor">
-    <input id="entryTitle" class="entry-title" type="text">
-    <section id="preview" class="preview"></section>
-    <section id="toolbar" class="toolbar"></section>
-    <textarea id="entryMarkdown" class="entry-markdown"></textarea>
-    <section class="actions">
-        <span id="status" class="status" aria-live="polite"></span>
-        <button id="save" type="button" disabled></button>
+<section class="markdown-editor" part="editor">
+    <input id="entryTitle" class="entry-title" part="title" type="text">
+    <section id="preview" class="preview" part="preview" tabindex="0"></section>
+    <section id="toolbar" class="toolbar" part="toolbar"></section>
+    <textarea id="entryMarkdown" class="entry-markdown" part="input"></textarea>
+    <section class="actions" part="actions">
+        <span id="status" class="status" part="status" aria-live="polite"></span>
+        <button id="save" part="save-action" type="button" disabled></button>
     </section>
 </section>
 
@@ -88,6 +137,7 @@
     const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
     const events=createArcaneEventSource(host,{source:'arcane.component.markdown-editor',eventTypes:['markdown-editor-change','markdown-editor-saved','markdown-editor-ready']});
     const lifecycleController=new AbortController();
+    const editor=host.shadowRoot.querySelector('.markdown-editor');
     const titleInput=host.shadowRoot.querySelector('#entryTitle');
     const preview=host.shadowRoot.querySelector('#preview');
     const toolbar=host.shadowRoot.querySelector('#toolbar');
@@ -96,6 +146,7 @@
     const status=host.shadowRoot.querySelector('#status');
 
     let previewFrame=0;
+    let previewFollowPending=false;
     let operationSequence=0;
     let saveGeneration=0;
     let saveController=null;
@@ -133,6 +184,9 @@
     titleInput.addEventListener('input',contentChanged,{signal:lifecycleController.signal});
     toolbar.addEventListener('click',formatMarkdown,{signal:lifecycleController.signal});
     saveButton.addEventListener('click',saveEntry,{signal:lifecycleController.signal});
+    for(const type of ['wheel','pointerdown','touchstart','keydown']){
+        preview.addEventListener(type,retainPreviewReadingPosition,{signal:lifecycleController.signal,passive:true});
+    }
 
     function optionsFromDataset(){
         const dataset=host.dataset||{};
@@ -151,6 +205,8 @@
         }
         for(const field of [
             'clearOnSave',
+            'fit',
+            'followPreview',
             'readOnly',
             'showPreview',
             'showSave',
@@ -191,8 +247,21 @@
     }
 
     function renderOptions(){
+        host.dataset.fit=String(options.fit);
+        editor.classList.toggle('fit',options.fit);
+        editor.classList.toggle('without-preview',!options.showPreview);
+        // Keyboard order follows the displayed order in each layout.
+        if(options.fit){
+            editor.insertBefore(toolbar,preview);
+            editor.insertBefore(textarea,preview);
+        }else{
+            editor.insertBefore(preview,toolbar);
+            editor.insertBefore(textarea,toolbar.nextSibling);
+        }
         titleInput.placeholder=options.labels.titlePlaceholder;
+        titleInput.setAttribute('aria-label',options.labels.titlePlaceholder);
         textarea.placeholder=options.labels.bodyPlaceholder;
+        textarea.setAttribute('aria-label',options.labels.bodyPlaceholder);
         preview.setAttribute('aria-label',options.labels.preview);
         preview.dataset.emptyLabel=options.labels.preview;
         toolbar.setAttribute('aria-label',options.labels.toolbar);
@@ -221,12 +290,14 @@
         toolbar.replaceChildren(fragment);
     }
 
-    function contentChanged(){
+    function contentChanged(event){
         if(destroyed){
             return;
         }
         supersedeSave('markdown-content-edited');
-        schedulePreview();
+        if(event?.currentTarget!==titleInput){
+            schedulePreview(options.followPreview);
+        }
         const detail={
             markdown:textarea.value,
             title:titleInput.value
@@ -239,17 +310,28 @@
         }
     }
 
-    function schedulePreview(){
+    function schedulePreview(follow=false){
         if(destroyed){
             return;
         }
         if(previewFrame){
             cancelAnimationFrame(previewFrame);
         }
-        previewFrame=requestAnimationFrame(updatePreview);
+        previewFollowPending=previewFollowPending||follow;
+        previewFrame=requestAnimationFrame(renderPendingPreview);
     }
 
-    function updatePreview(){
+    function renderPendingPreview(){
+        const follow=previewFollowPending;
+        previewFrame=0;
+        updatePreview(follow);
+    }
+
+    function retainPreviewReadingPosition(){
+        previewFollowPending=false;
+    }
+
+    function updatePreview(follow=false){
         if(destroyed){
             return;
         }
@@ -257,13 +339,87 @@
             cancelAnimationFrame(previewFrame);
         }
         previewFrame=0;
-        preview.innerHTML=new MD(textarea.value).safeRendered;
+        previewFollowPending=false;
+        const scrollTop=preview.scrollTop;
+        const scrollLeft=preview.scrollLeft;
+        const markdown=new MD(textarea.value,{sourceMap:options.followPreview});
+        preview.innerHTML=markdown.safeRendered;
         preview.querySelectorAll('a').forEach(
             link=>{
                 link.target='_blank';
                 link.removeAttribute('rel');
             }
         );
+        preview.scrollTop=scrollTop;
+        preview.scrollLeft=scrollLeft;
+        if(follow&&options.followPreview&&options.showPreview){
+            followTypingPosition(markdown.sourceMap);
+        }
+    }
+
+    function followTypingPosition(sourceMap){
+        const records=new Map(sourceMap.map(record=>[record.marker,record]));
+        const walker=document.createTreeWalker(preview,NodeFilter.SHOW_COMMENT);
+        const anchors=[];
+        for(let node=walker.nextNode();node;node=walker.nextNode()){
+            const record=records.get(node.data);
+            if(record){
+                anchors.push({node,record});
+            }
+        }
+        if(!anchors.length||!preview.clientHeight){
+            return;
+        }
+        const caret=textarea.selectionDirection==='backward'
+            ?textarea.selectionStart:textarea.selectionEnd;
+        let selected=0;
+        for(let index=0;index<anchors.length;index+=1){
+            if(anchors[index].record.start>caret){
+                break;
+            }
+            selected=index;
+        }
+        // Raw HTML can absorb an anchor or have no visible geometry. Use the
+        // nearest rendered block; never move the containing page or input pane.
+        let left=selected;
+        let right=selected+1;
+        while(left>=0||right<anchors.length){
+            const useLeft=right>=anchors.length||(
+                left>=0&&Math.abs(caret-anchors[left].record.end)<=Math.abs(anchors[right].record.start-caret)
+            );
+            const index=useLeft?left--:right++;
+            const anchor=anchors[index];
+            const range=document.createRange();
+            range.setStartAfter(anchor.node);
+            if(anchors[index+1]){
+                range.setEndBefore(anchors[index+1].node);
+            }else{
+                range.setEnd(preview,preview.childNodes.length);
+            }
+            const bounds=range.getBoundingClientRect();
+            if(!bounds.height){
+                continue;
+            }
+            const viewportTop=preview.getBoundingClientRect().top+preview.clientTop;
+            const viewportBottom=viewportTop+preview.clientHeight;
+            if(bounds.height<=preview.clientHeight){
+                if(bounds.top<viewportTop){
+                    preview.scrollTop+=bounds.top-viewportTop;
+                }else if(bounds.bottom>viewportBottom){
+                    preview.scrollTop+=bounds.bottom-viewportBottom;
+                }
+            }else{
+                // A top-level block may be a long paragraph, list or code fence.
+                // Follow approximate position within it without rewriting text.
+                const span=anchor.record.end-anchor.record.start;
+                const fraction=span?Math.max(0,Math.min(1,(caret-anchor.record.start)/span)):0;
+                const position=bounds.top+fraction*bounds.height;
+                if(position<viewportTop||position>viewportBottom){
+                    preview.scrollTop+=position-viewportTop-preview.clientHeight/2;
+                }
+            }
+            return;
+        }
     }
 
     function formatMarkdown(event){
@@ -414,6 +570,7 @@
         destroyed=true;
         supersedeSave('markdown-editor-destroyed');
         lifecycleController.abort('markdown-editor-destroyed');
+        previewFollowPending=false;
         if(previewFrame){
             cancelAnimationFrame(previewFrame);
             previewFrame=0;

package/runtime/arcane/entities/File.js

@@ -80,8 +80,22 @@ class FileEntity {
             (this.fileName.lastIndexOf('.')+1)
         ).toLowerCase();
 
+        // Storage may omit MIME metadata; preserve a supplied type before inferring audio.
+        const audioMimeTypes={
+            "mp3": "audio/mpeg",
+            "wav": "audio/wav",
+            "ogg": "audio/ogg",
+            "oga": "audio/ogg",
+            "opus": "audio/ogg",
+            "aac": "audio/aac",
+            "m4a": "audio/mp4",
+            "flac": "audio/flac",
+            "weba": "audio/webm"
+        };
+
         const mime=mimeTypes[file.ext]||
             file.type||
+            audioMimeTypes[file.ext]||
             'application/octet-stream';
 
         file.mime=mime;

package/runtime/arcane/modules/ComponentContracts.js

@@ -1101,6 +1101,8 @@ function normalizeMarkdownOptions(input={},previous={}){
         showPreview:option(input,previous,'showPreview',true)!==false,
         showToolbar:option(input,previous,'showToolbar',true)!==false,
         showSave:option(input,previous,'showSave',true)!==false,
+        fit:option(input,previous,'fit',false)===true,
+        followPreview:option(input,previous,'followPreview',false)===true,
         readOnly:option(input,previous,'readOnly',false)===true,
         clearOnSave:option(input,previous,'clearOnSave',true)!==false,
         onSave:optionalCallback(input,previous,['onSave','save'],'onSave'),

package/runtime/arcane/modules/MD.js

@@ -1,30 +1,36 @@
 import { arcaneLogging } from 'arcane-os/logging';
-import { marked } from './Marked.min.js';
+import { Marked, marked } from './Marked.min.js';
 import Is from 'strong-type';
 
-marked.use(
-    {
-        async: false,
-        pedantic: false,
-        gfm: true,
-        renderer: {
-            link(href, title, text) {
-                const link = marked.Renderer.prototype.link.call(this, href, title, text);
-                return link.replace("<a","<a target='_blank' ");
-            }
+const markdownOptions = {
+    async: false,
+    pedantic: false,
+    gfm: true,
+    renderer: {
+        link(href, title, text) {
+            const link = marked.Renderer.prototype.link.call(this, href, title, text);
+            return link.replace("<a","<a target='_blank' ");
         }
     }
-);
+};
+
+marked.use(markdownOptions);
 
 const is = new Is(false);
 
 class MD {
     #raw='';
-    #rendered=''
+    #rendered='';
+    #sourceMapEnabled=false;
+    #sourceMap=[];
 
-    constructor(raw=''){
+    constructor(raw='', options={}){
+        this.#sourceMapEnabled=options?.sourceMap===true;
         this.raw=raw;
-        this.rendered=marked.parse(raw);
+        if(!is.string(raw)){
+            // Preserve the constructor's existing Marked error for invalid input.
+            this.rendered=marked.parse(raw);
+        }
         return this;
     }
 
@@ -36,6 +42,10 @@ class MD {
         return this.#rendered;
     }
 
+    get sourceMap(){
+        return this.#sourceMap;
+    }
+
     set rendered(value=''){
         return this.#rendered;
     }
@@ -50,7 +60,7 @@ class MD {
             return this.#raw;
         }
         this.#raw = value;
-        this.#rendered = marked.parse(value);
+        this.#render();
         return this.#raw;
     }
 
@@ -60,9 +70,130 @@ class MD {
             return this.#raw;
         }
         this.#raw += value;
-        this.#rendered = marked.parse(this.#raw);
+        this.#render();
         return this.#raw;
     }
+
+    #render(){
+        if(!this.#sourceMapEnabled){
+            this.#rendered=marked.parse(this.#raw);
+            this.#sourceMap=[];
+            return;
+        }
+
+        const result=renderWithSourceMap(this.#raw);
+        this.#rendered=result.rendered;
+        this.#sourceMap=result.sourceMap;
+    }
+}
+
+function renderWithSourceMap(raw){
+    const tokenRanges=new WeakMap();
+    const sourceMap=[];
+    let normalizedEnd=0;
+    let normalizedOffset=0;
+    let originalOffset=0;
+    let observedRoot=false;
+    let previousOffset=0;
+    let previousCount=0;
+    let previousRaw;
+    const authoredGenerations=new Set();
+    for(const match of raw.matchAll(/arcane-md-source-(\d+):/g)){
+        authoredGenerations.add(match[1]);
+    }
+    let markerGeneration=0;
+    while(authoredGenerations.has(String(markerGeneration))){
+        markerGeneration++;
+    }
+    const markerPrefix=`arcane-md-source-${markerGeneration}:`;
+
+    function captureBoundary(tokens, offset){
+        // Follow Marked's CRLF/CR cursor without rewriting raw or retaining a per-character map.
+        while(normalizedOffset<offset){
+            if(raw[originalOffset]==='\r' && raw[originalOffset+1]==='\n'){
+                originalOffset++;
+            }
+            originalOffset++;
+            normalizedOffset++;
+        }
+        for(let index=previousCount; index<tokens.length; index++){
+            tokenRanges.set(
+                tokens[index],
+                {
+                    start:previousOffset,
+                    end:originalOffset
+                }
+            );
+        }
+
+        const last=tokens.at(-1);
+        if(tokens.length===previousCount && last && last.raw!==previousRaw){
+            // Marked can merge a newline or indented continuation into a prior token.
+            const range=tokenRanges.get(last);
+            if(range){
+                range.end=originalOffset;
+            }
+        }
+        previousOffset=originalOffset;
+        previousCount=tokens.length;
+        previousRaw=last?.raw;
+    }
+
+    const renderer={};
+    const blockTypes=['code','blockquote','html','heading','hr','list','paragraph','table','text'];
+    for(const type of blockTypes){
+        const render=marked.Renderer.prototype[type];
+        renderer[type]=function renderMappedBlock(token){
+            const html=render.call(this,token);
+            const range=tokenRanges.get(token);
+            if(!range || !html){
+                return html;
+            }
+
+            const marker=`${markerPrefix}${sourceMap.length}`;
+            sourceMap.push(
+                {
+                    start:range.start,
+                    end:range.end,
+                    marker,
+                    type:token.type
+                }
+            );
+            return `<!--${marker}-->${html}`;
+        };
+    }
+
+    const parser=new Marked(
+        markdownOptions,
+        {
+            extensions:[
+                {
+                    name:'arcaneSourceMap',
+                    level:'block',
+                    tokenizer(src,tokens){
+                        if(tokens===this.lexer.tokens){
+                            if(!observedRoot){
+                                normalizedEnd=src.length;
+                                observedRoot=true;
+                            }
+                            // Observe consumption, including definitions that produce no token.
+                            captureBoundary(tokens,normalizedEnd-src.length);
+                        }
+                        return undefined;
+                    }
+                }
+            ],
+            hooks:{
+                processAllTokens(tokens){
+                    captureBoundary(tokens,normalizedEnd);
+                    return tokens;
+                }
+            },
+            renderer
+        }
+    );
+    const rendered=parser.parse(raw);
+    return {rendered,sourceMap};
 }
 
 export default MD;