@jackuait/blok 0.18.0 → 0.19.0

package/dist/full.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/blok-B7IRrvgX.cjs`),t=require(`./chunks/constants-BWoyU4yv.cjs`),n=require(`./chunks/objectSpread2-iNkE6aJh.cjs`),r=require(`./chunks/tools-DXagFf6I.cjs`);var i={paragraph:{class:r.k,inlineToolbar:!0,config:{preserveBlank:!0}},header:{class:r.O,inlineToolbar:!0},list:{class:r.D,inlineToolbar:!0}},a=n.t(n.t({},i),{},{bold:{class:r.l},italic:{class:r.c},marker:{class:r.o},underline:{class:r.a},strikethrough:{class:r.i},link:{class:r.s}});exports.Blok=e.t,exports.Bold=r.l,exports.DATA_ATTR=t.Pi,exports.Header=r.O,exports.Italic=r.c,exports.Link=r.s,exports.List=r.D,exports.Marker=r.o,exports.Paragraph=r.k,exports.Strikethrough=r.i,exports.Toggle=r.T,exports.Underline=r.a,exports.allTools=a,exports.defaultBlockTools=r.t,exports.defaultInlineTools=r.n,exports.defaultTools=i,exports.version=e.n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/blok-BosfCfPX.cjs`),t=require(`./chunks/constants-ChsAFZ8F.cjs`),n=require(`./chunks/objectSpread2-iNkE6aJh.cjs`),r=require(`./chunks/tools-DmEzyrn3.cjs`);var i={paragraph:{class:r.k,inlineToolbar:!0,config:{preserveBlank:!0}},header:{class:r.O,inlineToolbar:!0},list:{class:r.D,inlineToolbar:!0}},a=n.t(n.t({},i),{},{bold:{class:r.l},italic:{class:r.c},marker:{class:r.o},underline:{class:r.a},strikethrough:{class:r.i},link:{class:r.s}});exports.Blok=e.t,exports.Bold=r.l,exports.DATA_ATTR=t.Pi,exports.Header=r.O,exports.Italic=r.c,exports.Link=r.s,exports.List=r.D,exports.Marker=r.o,exports.Paragraph=r.k,exports.Strikethrough=r.i,exports.Toggle=r.T,exports.Underline=r.a,exports.allTools=a,exports.defaultBlockTools=r.t,exports.defaultInlineTools=r.n,exports.defaultTools=i,exports.version=e.n;

package/dist/full.mjs

@@ -1,7 +1,7 @@
-import { n as e, t } from "./chunks/blok-BoAuTqli.mjs";
-import { Pi as n } from "./chunks/constants-BO6zLfL2.mjs";
+import { n as e, t } from "./chunks/blok-CXB-exXU.mjs";
+import { Pi as n } from "./chunks/constants-BmCvHbkL.mjs";
 import { t as r } from "./chunks/objectSpread2-jlBcdYeb.mjs";
-import { D as i, O as a, T as o, a as s, c, i as l, k as u, l as d, n as f, o as p, s as m, t as h } from "./chunks/tools-DRwLS-6t.mjs";
+import { D as i, O as a, T as o, a as s, c, i as l, k as u, l as d, n as f, o as p, s as m, t as h } from "./chunks/tools-BdoYHyV0.mjs";
 //#region src/full.ts
 var g = {
 	paragraph: {

package/dist/react.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunks/chunk-BL1yB9zm.cjs`);const e=require(`./chunks/blok-B7IRrvgX.cjs`),t=require(`./chunks/objectSpread2-iNkE6aJh.cjs`);let n=require(`react`),r=require(`react/jsx-runtime`);var i=new WeakMap;function a(e,t){i.set(e,t)}function o(e){return i.get(e)}function s(e){i.delete(e)}function c(r,i){let[o,c]=(0,n.useState)(null),u=(0,n.useRef)(r);u.current=r;let d=(0,n.useRef)({editor:null,holder:null,destroyTimeout:null,isDestroyed:!1,depsToken:null}),f=(0,n.useMemo)(()=>({}),i==null?[]:i);(0,n.useEffect)(()=>{if(typeof window>`u`)return;let n=d.current;if(n.destroyTimeout!==null&&(clearTimeout(n.destroyTimeout),n.destroyTimeout=null),n.editor!==null&&!n.isDestroyed&&n.depsToken===f)return c(n.editor),()=>{l(n,c)};if(n.editor!==null&&!n.isDestroyed){s(n.editor);try{n.editor.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}let r=document.createElement(`div`);n.holder=r,n.isDestroyed=!1,n.depsToken=f;let i=u.current,o=new e.t(t.t(t.t({},i),{},{holder:r,onReady:()=>{var e,t;(e=(t=u.current).onReady)==null||e.call(t)},onChange:(...e)=>{var t,n;(t=(n=u.current).onChange)==null||t.call(n,...e)}}));return n.editor=o,a(o,r),o.isReady.then(()=>{n.editor===o&&!n.isDestroyed&&c(o)}).catch(()=>{if(n.editor===o&&!n.isDestroyed){s(o);try{o.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}}),()=>{l(n,c)}},[f]);let{readOnly:p}=r;(0,n.useEffect)(()=>{o!==null&&o.readOnly.set(p==null?!1:p)},[o,p]);let{autofocus:m}=r;return(0,n.useEffect)(()=>{o===null||!m||o.focus()},[o,m]),o}function l(e,t){e.destroyTimeout=setTimeout(()=>{if(e.editor!==null){s(e.editor);try{e.editor.destroy()}catch(e){}e.editor=null,e.holder=null,e.isDestroyed=!0,e.destroyTimeout=null,t(null)}},0)}var u=[`editor`],d=(0,n.forwardRef)(function(i,a){let{editor:s}=i,c=e.i(i,u),l=(0,n.useRef)(null);return(0,n.useEffect)(()=>{if(s===null||l.current===null)return;let e=o(s);if(e!==void 0)return l.current.appendChild(e),()=>{e.remove()}},[s]),(0,r.jsx)(`div`,t.t({ref:e=>{if(l.current=e,typeof a==`function`)a(e);else if(a!=null){let t=a;t.current=e}}},c))});exports.BlokContent=d,exports.useBlok=c;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunks/chunk-BL1yB9zm.cjs`);const e=require(`./chunks/blok-BosfCfPX.cjs`),t=require(`./chunks/objectSpread2-iNkE6aJh.cjs`);let n=require(`react`),r=require(`react/jsx-runtime`);var i=new WeakMap;function a(e,t){i.set(e,t)}function o(e){return i.get(e)}function s(e){i.delete(e)}function c(r,i){let[o,c]=(0,n.useState)(null),u=(0,n.useRef)(r);u.current=r;let d=(0,n.useRef)({editor:null,holder:null,destroyTimeout:null,isDestroyed:!1,depsToken:null}),f=(0,n.useMemo)(()=>({}),i==null?[]:i);(0,n.useEffect)(()=>{if(typeof window>`u`)return;let n=d.current;if(n.destroyTimeout!==null&&(clearTimeout(n.destroyTimeout),n.destroyTimeout=null),n.editor!==null&&!n.isDestroyed&&n.depsToken===f)return c(n.editor),()=>{l(n,c)};if(n.editor!==null&&!n.isDestroyed){s(n.editor);try{n.editor.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}let r=document.createElement(`div`);n.holder=r,n.isDestroyed=!1,n.depsToken=f;let i=u.current,o=new e.t(t.t(t.t({},i),{},{holder:r,onReady:()=>{var e,t;(e=(t=u.current).onReady)==null||e.call(t)},onChange:(...e)=>{var t,n;(t=(n=u.current).onChange)==null||t.call(n,...e)}}));return n.editor=o,a(o,r),o.isReady.then(()=>{n.editor===o&&!n.isDestroyed&&c(o)}).catch(()=>{if(n.editor===o&&!n.isDestroyed){s(o);try{o.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}}),()=>{l(n,c)}},[f]);let{readOnly:p}=r;(0,n.useEffect)(()=>{o!==null&&o.readOnly.set(p==null?!1:p)},[o,p]);let{autofocus:m}=r;return(0,n.useEffect)(()=>{o===null||!m||o.focus()},[o,m]),o}function l(e,t){e.destroyTimeout=setTimeout(()=>{if(e.editor!==null){s(e.editor);try{e.editor.destroy()}catch(e){}e.editor=null,e.holder=null,e.isDestroyed=!0,e.destroyTimeout=null,t(null)}},0)}var u=[`editor`],d=(0,n.forwardRef)(function(i,a){let{editor:s}=i,c=e.i(i,u),l=(0,n.useRef)(null);return(0,n.useEffect)(()=>{if(s===null||l.current===null)return;let e=o(s);if(e!==void 0)return l.current.appendChild(e),()=>{e.remove()}},[s]),(0,r.jsx)(`div`,t.t({ref:e=>{if(l.current=e,typeof a==`function`)a(e);else if(a!=null){let t=a;t.current=e}}},c))});exports.BlokContent=d,exports.useBlok=c;

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { i as e, t } from "./chunks/blok-BoAuTqli.mjs";
+import { i as e, t } from "./chunks/blok-CXB-exXU.mjs";
 import { t as n } from "./chunks/objectSpread2-jlBcdYeb.mjs";
 import { forwardRef as r, useEffect as i, useMemo as a, useRef as o, useState as s } from "react";
 import { jsx as c } from "react/jsx-runtime";

package/dist/tools.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/constants-BWoyU4yv.cjs`),t=require(`./chunks/tools-DXagFf6I.cjs`);exports.Audio=t.g,exports.Bold=t.l,exports.Bookmark=t.u,exports.Callout=t.w,exports.Code=t.y,exports.Column=t.p,exports.ColumnList=t.m,exports.Columns=t.f,exports.Convert=e.m,exports.Database=t.C,exports.DatabaseRow=t.S,exports.Divider=t.x,exports.Embed=t.d,exports.File=t._,exports.Header=t.O,exports.Image=t.v,exports.InlineCode=t.r,exports.Italic=t.c,exports.Link=t.s,exports.List=t.D,exports.Marker=t.o,exports.Paragraph=t.k,exports.Quote=t.b,exports.Strikethrough=t.i,exports.Table=t.E,exports.Toggle=t.T,exports.Underline=t.a,exports.Video=t.h,exports.defaultBlockTools=t.t,exports.defaultInlineTools=t.n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/constants-ChsAFZ8F.cjs`),t=require(`./chunks/tools-DmEzyrn3.cjs`);exports.Audio=t.g,exports.Bold=t.l,exports.Bookmark=t.u,exports.Callout=t.w,exports.Code=t.y,exports.Column=t.p,exports.ColumnList=t.m,exports.Columns=t.f,exports.Convert=e.m,exports.Database=t.C,exports.DatabaseRow=t.S,exports.Divider=t.x,exports.Embed=t.d,exports.File=t._,exports.Header=t.O,exports.Image=t.v,exports.InlineCode=t.r,exports.Italic=t.c,exports.Link=t.s,exports.List=t.D,exports.Marker=t.o,exports.Paragraph=t.k,exports.Quote=t.b,exports.Strikethrough=t.i,exports.Table=t.E,exports.Toggle=t.T,exports.Underline=t.a,exports.Video=t.h,exports.defaultBlockTools=t.t,exports.defaultInlineTools=t.n;

package/dist/tools.mjs

@@ -1,3 +1,3 @@
-import { m as e } from "./chunks/constants-BO6zLfL2.mjs";
-import { C as t, D as n, E as r, O as i, S as a, T as o, _ as s, a as c, b as l, c as u, d, f, g as p, h as m, i as h, k as g, l as _, m as v, n as y, o as b, p as x, r as S, s as C, t as w, u as T, v as E, w as D, x as O, y as k } from "./chunks/tools-DRwLS-6t.mjs";
+import { m as e } from "./chunks/constants-BmCvHbkL.mjs";
+import { C as t, D as n, E as r, O as i, S as a, T as o, _ as s, a as c, b as l, c as u, d, f, g as p, h as m, i as h, k as g, l as _, m as v, n as y, o as b, p as x, r as S, s as C, t as w, u as T, v as E, w as D, x as O, y as k } from "./chunks/tools-BdoYHyV0.mjs";
 export { p as Audio, _ as Bold, T as Bookmark, D as Callout, k as Code, x as Column, v as ColumnList, f as Columns, e as Convert, t as Database, a as DatabaseRow, O as Divider, d as Embed, s as File, i as Header, E as Image, S as InlineCode, u as Italic, C as Link, n as List, b as Marker, g as Paragraph, l as Quote, h as Strikethrough, r as Table, o as Toggle, c as Underline, m as Video, w as defaultBlockTools, y as defaultInlineTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackuait/blok",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Blok — headless, highly extensible rich text editor built for developers who need to implement a block-based editing experience (similar to Notion) without building it from scratch",
   "module": "dist/blok.mjs",
   "main": "./dist/blok.cjs",

package/src/blok.ts

@@ -5,7 +5,7 @@
  */
 import '@babel/register';
 
-import type { BlokConfig, API } from '../types';
+import type { BlokConfig, API, EditorWidth } from '../types';
 
 import { DATA_ATTR } from './components/constants/data-attributes';
 import { Core } from './components/core';
@@ -141,6 +141,38 @@ class Blok {
       },
     };
 
+    /**
+     * Width API — expose it on the instance immediately (mirrors the theme API),
+     * so host apps can call instance.width.set('full') before isReady without a
+     * silent no-op. The chosen mode is buffered and replayed once UI is ready.
+     */
+    const widthBuffer = { pendingMode: null as EditorWidth | null };
+
+    const getUIModule = (): BlokModules['UI'] | undefined =>
+      (blok.moduleInstances as Partial<BlokModules>).UI;
+
+    const readWidthMode = (): EditorWidth => {
+      const ui = getUIModule();
+
+      return ui !== undefined ? ui.getWidthMode() : (widthBuffer.pendingMode ?? 'narrow');
+    };
+
+    const applyWidthMode = (mode: EditorWidth): void => {
+      widthBuffer.pendingMode = mode;
+
+      const ui = getUIModule();
+
+      if (ui !== undefined) {
+        ui.setWidthMode(mode);
+      }
+    };
+
+    (this as Record<string, unknown>).width = {
+      get: (): EditorWidth => readWidthMode(),
+      set: (mode: EditorWidth): void => applyWidthMode(mode),
+      toggle: (): void => applyWidthMode(readWidthMode() === 'full' ? 'narrow' : 'full'),
+    };
+
     /**
      * We need to export isReady promise in the constructor
      * as it can be used before other API methods are exported
@@ -203,6 +235,16 @@ class Blok {
         themeBuffer.pendingMode = null;
       }
 
+      // Apply any width mode buffered before isReady resolved.
+      if (widthBuffer.pendingMode !== null) {
+        const ui = (blok.moduleInstances as Partial<BlokModules>).UI;
+
+        if (ui !== undefined) {
+          ui.setWidthMode(widthBuffer.pendingMode);
+        }
+        widthBuffer.pendingMode = null;
+      }
+
       // Scroll to the block referenced by the URL hash, if present.
       // isReady resolves only after all blocks are in the DOM (requestIdleCallback fence in Renderer),
       // so no extra polling is needed even on slow connections.

package/src/components/constants/data-attributes.ts

@@ -63,6 +63,8 @@ export const DATA_ATTR = {
   contentAlign: 'data-blok-content-align',
   /** Right-to-left mode */
   rtl: 'data-blok-rtl',
+  /** Editor content width mode (present with value "full" for wide mode; absent = narrow) */
+  width: 'data-blok-width',
 
   // ============================================
   // Drag and Drop

package/src/components/modules/ui.ts

@@ -3,6 +3,7 @@
  * Module UI
  * @type {UI}
  */
+import type { EditorWidth } from '../../../types/api/width';
 import styles from '../../styles/main.css?inline';
 import { Module } from '../__module';
 import {
@@ -347,6 +348,35 @@ export class UI extends Module<UINodes> {
     this.nodes.wrapper.setAttribute(DATA_ATTR.empty, BlockManager.isBlokEmpty ? 'true' : 'false');
   }
 
+  /**
+   * Current editor content width mode. Defaults to 'narrow'.
+   */
+  private widthMode: EditorWidth = 'narrow';
+
+  /**
+   * Returns the current editor content width mode.
+   */
+  public getWidthMode(): EditorWidth {
+    return this.widthMode;
+  }
+
+  /**
+   * Sets the editor content width mode by writing the width data attribute on
+   * the editor wrapper. 'narrow' (the default) leaves the attribute absent so
+   * the content keeps its `--max-width-content` constraint; 'full' adds it so
+   * the dedicated CSS rule removes the constraint.
+   * @param mode - the width mode to apply
+   */
+  public setWidthMode(mode: EditorWidth): void {
+    this.widthMode = mode;
+
+    if (mode === 'full') {
+      this.nodes.wrapper.setAttribute(DATA_ATTR.width, 'full');
+    } else {
+      this.nodes.wrapper.removeAttribute(DATA_ATTR.width);
+    }
+  }
+
   /**
    * Check if one of Toolbar is opened
    * Used to prevent global keydowns (for example, Enter) conflicts with Enter-on-toolbar

package/src/styles/audio.css

@@ -25,6 +25,9 @@
   --blok-audio-play-size: 36px;
   --blok-audio-bar: var(--blok-border-subtle);
   --blok-audio-bar-played: var(--blok-text-primary);
+  /* Comet-head tint — played colour nudged toward the editor accent. Subtle by
+     design; the waveform canvas blends bars toward it only at the playhead. */
+  --blok-audio-bar-head: color-mix(in srgb, var(--blok-audio-bar-played) 68%, var(--blok-color-accent) 32%);
   --blok-audio-seek-pct: 0%;
   --blok-audio-vol-pct: 100%;
   --blok-audio-speed-pct: 50%;

package/src/styles/main.css

@@ -273,6 +273,17 @@
   margin-left: auto;
 }
 
+/**
+ * Content width mode
+ * 'full' (data-blok-width="full" on the editor wrapper) removes the
+ * --max-width-content constraint so content fills its container. The default
+ * 'narrow' mode leaves the attribute absent and keeps the max-w-blok-content
+ * Tailwind utility intact. Unlayered selector overrides the @layer utilities rule.
+ */
+[data-blok-width="full"] [data-blok-element-content] {
+  max-width: none;
+}
+
 /**
  * Multi-block drag visual feedback
  * Makes selected blocks semi-transparent during multi-block drag operation

package/src/tools/audio/liveliness.ts

@@ -0,0 +1,136 @@
+/**
+ * Waveform "now playing" liveliness math.
+ *
+ * The cached peaks are static — there's no real-time FFT — so the sense of a
+ * live visualizer is composed from two layers:
+ *
+ *   1. A focal **comet** at the playhead: a bright head spike, a tight leading
+ *      edge, and a longer decaying wake trailing into the already-played bars.
+ *      It travels left→right as playback advances.
+ *   2. A global **ambient** ripple that flows across the entire field so no bar
+ *      sits frozen. It's biased stronger on the played side (a shimmering wake
+ *      of music) and faint on the not-yet-played preview ahead.
+ *
+ * All functions are pure so the behaviour is unit-testable; the canvas in
+ * waveform.ts just samples them per bar, per frame.
+ */
+
+/** Bars ahead of the playhead (not yet played) that still react. */
+export const REACH_AHEAD = 4;
+/** Bars behind the playhead (already played) that keep a decaying wake. */
+export const REACH_BEHIND = 9;
+
+/**
+ * Asymmetric "comet" falloff around the playhead. `distance` is the bar index
+ * minus the fractional playhead index: negative = behind (already-played wake),
+ * positive = ahead (not yet played). The wake reaches further than the leading
+ * edge so the energy reads as travelling with momentum. 1 at the playhead,
+ * easing to 0 at the respective reach.
+ */
+export function cometEnvelope(distance: number, reachAhead = REACH_AHEAD, reachBehind = REACH_BEHIND): number {
+  const reach = distance < 0 ? reachBehind : reachAhead;
+  const d = Math.abs(distance);
+  if (d >= reach) return 0;
+  const t = 1 - d / reach;
+  return t * t;
+}
+
+/**
+ * Tight symmetric spike centred on the playhead so the bar under it stands
+ * clearly proud of its neighbours — the bright head of the comet. Falls off
+ * faster (cubed) than the comet body.
+ */
+export function headFocus(distance: number, reach = 3): number {
+  const d = Math.abs(distance);
+  if (d >= reach) return 0;
+  const t = 1 - d / reach;
+  return t * t * t;
+}
+
+/**
+ * Deterministic per-bar wobble in [-1, 1]. Two out-of-phase sines keyed to the
+ * bar index so neighbouring bars rise and fall independently — the cluster
+ * reads as a dancing equalizer rather than one uniform swell.
+ */
+export function barWobble(index: number, timeSeconds: number): number {
+  const a = Math.sin(timeSeconds * 8.5 + index * 0.7);
+  const b = Math.sin(timeSeconds * 5.3 + index * 1.9);
+  return a * 0.6 + b * 0.4;
+}
+
+/**
+ * Slow travelling undulation across the whole bar field, in [-1, 1]. Two waves
+ * propagate in opposite directions (the `-index`/`+index` phase terms) so the
+ * field gently churns rather than sliding uniformly. Kept low-frequency so the
+ * motion is graceful, not busy.
+ */
+export function ambientWave(index: number, timeSeconds: number): number {
+  const a = Math.sin(timeSeconds * 2.1 - index * 0.35);
+  const b = Math.sin(timeSeconds * 1.3 + index * 0.21);
+  return a * 0.6 + b * 0.4;
+}
+
+/** Ambient swing applied to every bar (the faint preview-side breath). */
+const AMBIENT_BASE = 0.035;
+/** Extra ambient swing layered onto the played side (the shimmering wake). */
+const AMBIENT_PLAYED = 0.06;
+/** Bars ahead of the playhead over which the played-side shimmer fades out. */
+const AMBIENT_AHEAD_FADE = 26;
+
+/**
+ * Ease-out cubic for the head-colour entrance ramp: 0→1 with most of the travel
+ * up front, so the colour blooms in quickly then settles. Clamped to [0, 1].
+ */
+export function entranceEase(progress: number): number {
+  const t = Math.min(1, Math.max(0, progress));
+  return 1 - (1 - t) ** 3;
+}
+
+/**
+ * 0..1 tint strength for a bar's comet-head colour overlay. Peaks at the
+ * playhead (via {@link headFocus}) and scales with both the live `energy` (so it
+ * fades out on the pause settle) and the `entrance` ramp (so it animates in when
+ * playback starts).
+ */
+export function headColorBlend(opts: { distance: number; energy: number; entrance: number }): number {
+  return headFocus(opts.distance) * opts.energy * opts.entrance;
+}
+
+interface LiveAmplitudeOptions {
+  basePeak: number;
+  index: number;
+  /** Fractional bar position of the playhead (played * peaks.length). */
+  playheadIndex: number;
+  timeSeconds: number;
+  reduced: boolean;
+  /** 0..1 multiplier on the live boost — 1 while playing, ramps to 0 on the pause settle. */
+  energy?: number;
+}
+
+/**
+ * Final 0..1 bar amplitude, blending the static peak with two live layers: the
+ * playhead-localized comet (body swell + bright head spike + bidirectional
+ * dance) and a global ambient ripple biased toward the played side. The
+ * combined boost is scaled by `energy` (for the pause settle) and zeroed under
+ * `reduced` (prefers-reduced-motion).
+ */
+export function liveAmplitude(opts: LiveAmplitudeOptions): number {
+  const { basePeak, index, playheadIndex, timeSeconds, reduced, energy = 1 } = opts;
+  if (reduced || energy <= 0) return basePeak;
+
+  const distance = index - playheadIndex;
+
+  // Layer 1 — focal comet near the playhead.
+  const env = cometEnvelope(distance);
+  const head = headFocus(distance);
+  const comet = env * 0.15 + head * 0.2 + env * 0.28 * barWobble(index, timeSeconds);
+
+  // Layer 2 — global ambient ripple. Full strength behind the playhead (the
+  // played wake), fading across AMBIENT_AHEAD_FADE bars into the preview ahead.
+  const playedBias = distance <= 0 ? 1 : Math.max(0, 1 - distance / AMBIENT_AHEAD_FADE);
+  const ambient = ambientWave(index, timeSeconds) * (AMBIENT_BASE + AMBIENT_PLAYED * playedBias);
+
+  const amp = basePeak + (comet + ambient) * energy;
+
+  return Math.min(1, Math.max(0, amp));
+}

package/src/tools/audio/waveform.ts

@@ -1,4 +1,5 @@
 import { WAVEFORM_BUCKETS } from './constants';
+import { liveAmplitude, headColorBlend, entranceEase } from './liveliness';
 
 /**
  * Reduce raw mono samples to `buckets` peak values normalized to 0..1.
@@ -95,16 +96,51 @@ export function attachWaveform(opts: {
   canvas.className = 'blok-audio-waveform__canvas';
   mount.appendChild(canvas);
 
-  const draw = (): void => {
+  const prefersReducedMotion = (): boolean =>
+    globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+  // Animation state. `playing` is true between play and pause/ended and pins the
+  // boost energy at full. On pause we keep the loop alive briefly with `settling`
+  // so the bars glide back to their resting peaks (energy ramps 1→0) instead of
+  // snapping. `energy` reflects the current boost multiplier.
+  const SETTLE_MS = 420;
+  // The comet-head colour blooms in over ENTRANCE_MS each time playback starts.
+  const ENTRANCE_MS = 650;
+  const anim = { playing: false, settling: false, settleStart: 0, entranceStart: 0, rafId: 0 };
+
+  const energyAt = (now: number): number => {
+    if (anim.playing) return 1;
+    if (!anim.settling) return 0;
+    return Math.min(1, Math.max(0, 1 - (now - anim.settleStart) / SETTLE_MS));
+  };
+
+  const entranceAt = (now: number): number => entranceEase((now - anim.entranceStart) / ENTRANCE_MS);
+
+  const draw = (now: number): void => {
     const rect = canvas.getBoundingClientRect();
     if (rect.width <= 0 || rect.height <= 0) return;
     const dpr = globalThis.devicePixelRatio || 1;
-    canvas.width = Math.round(rect.width * dpr);
-    canvas.height = Math.round(rect.height * dpr);
+    const targetW = Math.round(rect.width * dpr);
+    const targetH = Math.round(rect.height * dpr);
+    // Resizing the backing store clears it; only pay that cost when the box
+    // actually changed (every frame of the loop would otherwise reallocate).
+    if (canvas.width !== targetW || canvas.height !== targetH) {
+      canvas.width = targetW;
+      canvas.height = targetH;
+    }
     const ctx = canvas.getContext('2d');
     if (!ctx) return;
-    ctx.scale(dpr, dpr);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, rect.width, rect.height);
+
     const played = media.duration ? media.currentTime / media.duration : 0;
+    const playheadIndex = played * peaks.length;
+    const reduced = prefersReducedMotion();
+    const timeSeconds = now / 1000;
+    const energy = reduced ? 0 : energyAt(now);
+    const live = energy > 0;
+    const entrance = live ? entranceAt(now) : 0;
+
     const slot = rect.width / peaks.length;
     const gap = Math.min(2, slot * 0.34);
     const barW = Math.max(1, slot - gap);
@@ -112,11 +148,9 @@ export function attachWaveform(opts: {
     const styles = getComputedStyle(canvas);
     const playedColor = styles.getPropertyValue('--blok-audio-bar-played').trim() || '#222';
     const baseColor = styles.getPropertyValue('--blok-audio-bar').trim() || '#ccc';
-    peaks.forEach((peak, i) => {
-      const h = Math.max(2, peak * rect.height * 0.92);
-      const x = i * slot;
-      const y = (rect.height - h) / 2;
-      ctx.fillStyle = i / peaks.length < played ? playedColor : baseColor;
+    const headColor = styles.getPropertyValue('--blok-audio-bar-head').trim() || playedColor;
+
+    const paintBar = (x: number, y: number, h: number): void => {
       if (typeof ctx.roundRect === 'function') {
         ctx.beginPath();
         ctx.roundRect(x, y, barW, h, radius);
@@ -124,26 +158,91 @@ export function attachWaveform(opts: {
       } else {
         ctx.fillRect(x, y, barW, h);
       }
+    };
+
+    peaks.forEach((peak, i) => {
+      const amp = live
+        ? liveAmplitude({ basePeak: peak, index: i, playheadIndex, timeSeconds, reduced, energy })
+        : peak;
+      const h = Math.max(2, amp * rect.height * 0.92);
+      const x = i * slot;
+      const y = (rect.height - h) / 2;
+      ctx.fillStyle = i < playheadIndex ? playedColor : baseColor;
+      paintBar(x, y, h);
+
+      // Comet-head colour shift — overlay the head tint, its alpha ramping in
+      // with the entrance and fading out on the settle (energy).
+      if (live) {
+        const blend = headColorBlend({ distance: i - playheadIndex, energy, entrance });
+        if (blend > 0.001) {
+          ctx.save();
+          ctx.globalAlpha = Math.min(1, blend);
+          ctx.fillStyle = headColor;
+          paintBar(x, y, h);
+          ctx.restore();
+        }
+      }
     });
   };
 
-  const rafState = { id: 0 };
+  const setSeekVar = (): void => {
+    mount.style.setProperty(
+      '--blok-audio-seek-pct',
+      String(media.duration ? (media.currentTime / media.duration) * 100 : 0),
+    );
+  };
+
+  const loop = (now: number): void => {
+    draw(now);
+    // Keep looping while playing, or while the post-pause settle still has energy.
+    const keepGoing = anim.playing || (anim.settling && energyAt(now) > 0);
+    if (keepGoing) {
+      anim.rafId = requestAnimationFrame(loop);
+    } else {
+      anim.settling = false;
+      anim.rafId = 0;
+    }
+  };
+
+  const onPlay = (): void => {
+    setSeekVar();
+    anim.playing = true;
+    anim.settling = false;
+    // Restart the head-colour entrance so it blooms in on every play.
+    anim.entranceStart = globalThis.performance?.now?.() ?? 0;
+    // No continuous loop under reduced motion — timeupdate alone advances the
+    // played boundary, with no dancing bars.
+    if (!anim.rafId && !prefersReducedMotion()) anim.rafId = requestAnimationFrame(loop);
+  };
+  const onStop = (): void => {
+    // Hand off to the settle ramp so the bars glide down rather than snap. Under
+    // reduced motion there's no loop/boost to settle, so just stop.
+    if (anim.playing && !prefersReducedMotion()) {
+      anim.playing = false;
+      anim.settling = true;
+      anim.settleStart = globalThis.performance?.now?.() ?? 0;
+      if (!anim.rafId) anim.rafId = requestAnimationFrame(loop);
+    } else {
+      anim.playing = false;
+      anim.settling = false;
+      if (anim.rafId) { cancelAnimationFrame(anim.rafId); anim.rafId = 0; }
+      draw(0);
+    }
+  };
+
+  // Keeps the played boundary + seek var current while paused-seeking or when
+  // the continuous loop is off (reduced motion). The loop owns drawing while it
+  // runs, so skip the redundant paint then.
   const onTime = (): void => {
-    if (rafState.id) return;
-    rafState.id = requestAnimationFrame(() => {
-      rafState.id = 0;
-      mount.style.setProperty(
-        '--blok-audio-seek-pct',
-        String(media.duration ? (media.currentTime / media.duration) * 100 : 0),
-      );
-      draw();
-    });
+    setSeekVar();
+    if (!anim.rafId) draw(0);
   };
 
   const seek = (clientX: number): void => {
     if (!media.duration) return;
     media.currentTime = ratioFromPointer(clientX, canvas.getBoundingClientRect()) * media.duration;
-    draw();
+    setSeekVar();
+    if (!anim.rafId) draw(0);
   };
   const drag = { active: false };
   const onDown = (e: PointerEvent): void => { drag.active = true; seek(e.clientX); };
@@ -153,18 +252,25 @@ export function attachWaveform(opts: {
   canvas.addEventListener('pointerdown', onDown);
   globalThis.addEventListener('pointermove', onMove);
   globalThis.addEventListener('pointerup', onUp);
+  media.addEventListener('play', onPlay);
+  media.addEventListener('pause', onStop);
+  media.addEventListener('ended', onStop);
   media.addEventListener('timeupdate', onTime);
-  media.addEventListener('loadedmetadata', draw);
-  draw();
+  media.addEventListener('loadedmetadata', onTime);
+  draw(0);
 
   return {
     destroy(): void {
-      if (rafState.id) cancelAnimationFrame(rafState.id);
+      if (anim.rafId) cancelAnimationFrame(anim.rafId);
+      anim.playing = false;
       canvas.removeEventListener('pointerdown', onDown);
       globalThis.removeEventListener('pointermove', onMove);
       globalThis.removeEventListener('pointerup', onUp);
+      media.removeEventListener('play', onPlay);
+      media.removeEventListener('pause', onStop);
+      media.removeEventListener('ended', onStop);
       media.removeEventListener('timeupdate', onTime);
-      media.removeEventListener('loadedmetadata', draw);
+      media.removeEventListener('loadedmetadata', onTime);
       canvas.remove();
     },
   };

package/types/api/index.d.ts

@@ -18,3 +18,4 @@ export * from './ui';
 export * from './tools';
 
 export * from './theme';
+export * from './width';

package/types/api/width.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Editor content width mode.
+ *
+ * - `'narrow'` — content is constrained to the default `--max-width-content` (the default).
+ * - `'full'`   — content max-width constraint is removed so it fills its container.
+ */
+export type EditorWidth = 'full' | 'narrow';
+
+/**
+ * Describes Blok's width API for controlling the editor content width mode.
+ */
+export interface Width {
+  /**
+   * Returns the current editor content width mode.
+   *
+   * @returns {EditorWidth} the active mode (defaults to `'narrow'`)
+   */
+  get(): EditorWidth;
+
+  /**
+   * Sets the editor content width mode.
+   *
+   * @param {EditorWidth} value - the mode to apply
+   */
+  set(value: EditorWidth): void;
+
+  /**
+   * Toggles the editor content width mode between `'narrow'` and `'full'`.
+   */
+  toggle(): void;
+}

package/types/data-attributes.d.ts

@@ -28,6 +28,7 @@ export const DATA_ATTR: {
 
   // Editor Modes
   readonly rtl: 'data-blok-rtl';
+  readonly width: 'data-blok-width';
 
   // Drag and Drop
   readonly dragging: 'data-blok-dragging';

package/types/index.d.ts

@@ -33,6 +33,7 @@ import {
   Theme,
   ThemeMode,
   ResolvedTheme,
+  Width,
 } from './api';
 
 import { OutputData } from './data-formats';
@@ -129,6 +130,8 @@ export {
   Theme,
   ThemeMode,
   ResolvedTheme,
+  Width,
+  EditorWidth,
 } from './api';
 export {
   BlockMutationType,
@@ -212,6 +215,7 @@ export class Blok {
 
   public blocks: Blocks;
   public caret: Caret;
+  public history: History;
   public sanitizer: Sanitizer;
   public saver: Saver;
   public selection: Selection;
@@ -221,6 +225,7 @@ export class Blok {
   public tooltip: Tooltip;
   public readOnly: ReadOnly;
   public theme: Theme;
+  public width: Width;
   constructor(configuration?: BlokConfig|string);
 
   /**