@mosetta/ui 0.0.0-stage → 0.0.10

package/src/components/styler.tsx

@@ -0,0 +1,229 @@
+import { useState } from 'react';
+import { STYLE_PROPERTIES } from '@mosetta/core';
+import type { IStyleProperty, IStyleVariable, TStyles, TStyleState } from '@mosetta/core';
+import { cn } from '../cn';
+
+// The form half of the STYLER (the runtime half is `useStyler` in @mosetta/react): a block's
+// editor facet drops it in with the block's parts and the node's `styles` setting, and its users
+// restyle each part — always, under the pointer, or on a narrow screen — from the properties the
+// styler allows. Only the properties set are listed; "Add a style" offers the rest by group.
+//
+//   <StylerForm parts={[{ name: 'root', label: 'Button' }]}
+//               value={draft.styles}
+//               variables={useThemeVariables()}
+//               onChange={(styles) => update({ styles })} />
+//
+// `variables` — the theme variables around the block (the editor knows them): a colour, a font or
+// a size may name one (`var(--theme-accent)`) instead of a literal, and follows the theme then.
+
+export interface IStylerPart {
+  /** the name the block's runtime marks the element with (`styler.part('root')`) */
+  readonly name: string;
+  /** what the form calls it */
+  readonly label: string;
+}
+
+export interface IStylerFormProps {
+  readonly parts: readonly IStylerPart[];
+  readonly value: TStyles | undefined;
+  readonly onChange: (styles: TStyles) => void;
+  /** the theme variables a value may name; none — literals only */
+  readonly variables?: readonly IStyleVariable[];
+}
+
+const STATES: readonly { state: TStyleState; label: string; hint: string }[] = [
+  { state: 'base', label: 'Always', hint: 'How the part looks' },
+  { state: 'hover', label: 'Hover', hint: 'Under the pointer' },
+  { state: 'current', label: 'Current', hint: 'The link to where the reader is: this page, the chosen category or language' },
+  { state: 'mobile', label: 'Mobile', hint: 'On screens up to 640px wide' },
+];
+
+const GROUP_LABELS: Record<IStyleProperty['group'], string> = {
+  text: 'Text',
+  box: 'Box',
+  border: 'Border',
+  layout: 'Layout',
+  effects: 'Effects',
+};
+
+const tab = (active: boolean) => cn(
+  'dui:h-7 dui:rounded-md dui:px-2 dui:text-xs dui:font-medium',
+  active ? 'dui:bg-foreground dui:text-background' : 'dui:text-muted-foreground dui:hover:bg-accent',
+);
+
+const HEX = /^#[0-9a-f]{6}$/i;
+const VAR_RE = /^var\((--[a-z0-9-]+)\)$/;
+
+/** which theme variables suit a property: colours for a colour, fonts for a font, the rest for sizes */
+function kindOf(property: IStyleProperty): IStyleVariable['kind'] | null {
+  if (property.input === 'choice') return null;
+  if (property.input === 'color') return 'color';
+  return property.name === 'fontFamily' ? 'font' : 'value';
+}
+
+function PropertyInput({ property, value, onChange, variables }: {
+  property: IStyleProperty;
+  value: string;
+  onChange: (value: string) => void;
+  variables: readonly IStyleVariable[];
+}) {
+  const field = 'dui:h-8 dui:w-full dui:min-w-0 dui:rounded-md dui:border dui:border-input dui:bg-transparent dui:px-2 dui:text-sm';
+  const kind = kindOf(property);
+  const suitable = kind ? variables.filter((v) => v.kind === kind) : [];
+  const named = VAR_RE.exec(value.trim())?.[1] ?? null;
+  const variable = named ? variables.find((v) => v.name === named) ?? null : null;
+  // a value naming a variable shows that variable's colour in the swatch
+  const swatch = variable?.value ?? value;
+  // naming a variable, the list IS the value (the text field steps aside); a literal keeps the
+  // field and a narrow list beside it
+  const themed = suitable.length ? (
+    <select className={variable
+      ? 'dui:h-8 dui:w-full dui:min-w-0 dui:rounded-md dui:border dui:border-input dui:bg-transparent dui:px-2 dui:text-sm'
+      : 'dui:h-8 dui:w-9 dui:shrink-0 dui:rounded-md dui:border dui:border-input dui:bg-transparent dui:px-1 dui:text-sm'}
+            aria-label={`${property.label} from the theme`}
+            data-style-variable={property.name}
+            data-tooltip="Take it from the theme: it changes with the theme"
+            value={variable ? variable.name : ''}
+            onChange={(e) => onChange(e.target.value ? `var(${e.target.value})` : (variable?.value ?? ''))}>
+      {/* closed, a literal's list is a glyph wide — the field keeps the room */}
+      <option value="">{variable ? 'a value of its own' : '◐'}</option>
+      {suitable.map((v) => <option key={v.name}
+                                   value={v.name}>{v.label}{v.value ? ` · ${v.value}` : ''}</option>)}
+    </select>
+  ) : null;
+  if (property.input === 'choice') {
+    return (
+      <select className={field}
+              value={value}
+              data-style-field={property.name}
+              onChange={(e) => onChange(e.target.value)}>
+        <option value="">—</option>
+        {property.choices!.map((c) => <option key={c}
+                                              value={c}>{c}</option>)}
+      </select>
+    );
+  }
+  return (
+    <div className="dui:flex dui:w-full dui:min-w-0 dui:items-center dui:gap-1">
+      {property.input === 'color' && (
+        <input type="color"
+               aria-label={`${property.label} colour`}
+               className="dui:h-8 dui:w-8 dui:shrink-0 dui:cursor-pointer dui:rounded-md dui:border dui:border-input dui:bg-transparent dui:p-0.5"
+               value={HEX.test(swatch) ? swatch : '#000000'}
+               onChange={(e) => onChange(e.target.value)} />
+      )}
+      {variable ? null : (
+        <input className={field}
+               value={value}
+               placeholder={property.placeholder ?? (property.input === 'color' ? '#1b1f33 or var(--theme-accent)' : '')}
+               spellCheck={false}
+               data-style-field={property.name}
+               onChange={(e) => onChange(e.target.value)} />
+      )}
+      {themed}
+    </div>
+  );
+}
+
+const NO_VARIABLES: readonly IStyleVariable[] = [];
+
+export function StylerForm({ parts, value, onChange, variables = NO_VARIABLES }: IStylerFormProps) {
+  const [part, setPart] = useState(parts[0]?.name ?? 'root');
+  const [state, setState] = useState<TStyleState>('base');
+  const styles = value ?? {};
+  const declarations = styles[part]?.[state] ?? {};
+  const set = Object.keys(declarations);
+
+  const write = (next: Record<string, string>) => {
+    const partStyles = { ...styles[part], [state]: next };
+    if (!Object.keys(next).length) delete (partStyles as Record<string, unknown>)[state];
+    const all = { ...styles, [part]: partStyles };
+    if (!Object.keys(partStyles).length) delete (all as Record<string, unknown>)[part];
+    onChange(all);
+  };
+  const remaining = STYLE_PROPERTIES.filter((p) => !set.includes(p.name));
+  const groups = [...new Set(remaining.map((p) => p.group))];
+
+  return (
+    // the styles of a block's parts: in an editor's settings, the Styles tab (data-inspector-tab)
+    <div className="dui:flex dui:flex-col dui:gap-2"
+         data-styler
+         data-inspector-tab="styles">
+      {parts.length > 1 && (
+        <div className="dui:flex dui:flex-wrap dui:gap-1"
+             role="tablist"
+             aria-label="Part">
+          {parts.map((p) => (
+            <button key={p.name}
+                    type="button"
+                    role="tab"
+                    aria-selected={p.name === part}
+                    className={tab(p.name === part)}
+                    data-styler-part={p.name}
+                    data-tooltip={`Style the ${p.label.toLowerCase()}`}
+                    onClick={() => setPart(p.name)}>
+              {p.label}
+              {styles[p.name] ? ' •' : ''}
+            </button>
+          ))}
+        </div>
+      )}
+      <div className="dui:flex dui:gap-1"
+           role="tablist"
+           aria-label="When">
+        {STATES.map((s) => (
+          <button key={s.state}
+                  type="button"
+                  role="tab"
+                  aria-selected={s.state === state}
+                  className={tab(s.state === state)}
+                  data-styler-state={s.state}
+                  data-tooltip={s.hint}
+                  onClick={() => setState(s.state)}>
+            {s.label}
+            {styles[part]?.[s.state] ? ' •' : ''}
+          </button>
+        ))}
+      </div>
+      {set.map((name) => {
+        const property = STYLE_PROPERTIES.find((p) => p.name === name)!;
+        return (
+          <div key={name}
+               className="dui:grid dui:grid-cols-[96px_1fr_auto] dui:items-center dui:gap-2">
+            <span className="dui:truncate dui:text-xs dui:text-muted-foreground">{property.label}</span>
+            <PropertyInput property={property}
+                           value={declarations[name] ?? ''}
+                           variables={variables}
+                           onChange={(v) => write({ ...declarations, [name]: v })} />
+            <button type="button"
+                    className="dui:h-8 dui:w-8 dui:rounded-md dui:text-muted-foreground dui:hover:bg-accent"
+                    aria-label={`Remove ${property.label}`}
+                    data-tooltip={`Remove ${property.label.toLowerCase()} — the block's own look comes back`}
+                    onClick={() => {
+                      const { [name]: _gone, ...rest } = declarations;
+                      write(rest);
+                    }}>
+              ×
+            </button>
+          </div>
+        );
+      })}
+      <select className="dui:h-8 dui:w-full dui:rounded-md dui:border dui:border-dashed dui:border-input dui:bg-transparent dui:px-2 dui:text-sm dui:text-muted-foreground"
+              value=""
+              data-styler-add
+              aria-label="Add a style"
+              onChange={(e) => {
+                if (e.target.value) write({ ...declarations, [e.target.value]: '' });
+              }}>
+        <option value="">{set.length ? 'Add another style…' : 'Add a style…'}</option>
+        {groups.map((g) => (
+          <optgroup key={g}
+                    label={GROUP_LABELS[g]}>
+            {remaining.filter((p) => p.group === g).map((p) => <option key={p.name}
+                                                                       value={p.name}>{p.label}</option>)}
+          </optgroup>
+        ))}
+      </select>
+    </div>
+  );
+}

package/src/components/typography.tsx

@@ -0,0 +1,98 @@
+// Typography primitives for the ui-kit distributive (heading/text protocol modules render these).
+// Not shadcn canon — but same conventions: variants + `dui:` prefix (scoped tailwind).
+import { type HTMLAttributes } from 'react';
+import { cn } from '../cn';
+import { variants, type VariantProps } from '../variants';
+
+const headingVariants = variants({
+  base: 'dui:text-foreground dui:tracking-tight',
+  variants: {
+    level: {
+      1: 'dui:text-4xl dui:font-extrabold',
+      2: 'dui:text-3xl dui:font-semibold',
+      3: 'dui:text-2xl dui:font-semibold',
+      4: 'dui:text-xl dui:font-semibold',
+    },
+  },
+  defaultVariants: { level: 2 },
+});
+
+export interface IHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  readonly level?: 1 | 2 | 3 | 4;
+}
+
+export function Heading({ level = 2, className, ...props }: IHeadingProps) {
+  const Tag = `h${level}` as const;
+  return <Tag className={headingVariants({ level, className })}
+              {...props} />;
+}
+
+const textVariants = variants({
+  base: 'dui:text-foreground',
+  variants: {
+    tone: {
+      default: '',
+      muted: 'dui:text-muted-foreground',
+      destructive: 'dui:text-destructive',
+    },
+    size: {
+      sm: 'dui:text-sm',
+      default: 'dui:text-base',
+      lg: 'dui:text-lg',
+    },
+  },
+  defaultVariants: { tone: 'default', size: 'default' },
+});
+
+export interface ITextProps
+  extends HTMLAttributes<HTMLParagraphElement>,
+  VariantProps<{ tone: Record<'default' | 'muted' | 'destructive', string>;
+    size: Record<'sm' | 'default' | 'lg', string> }> {}
+
+export function Text({ tone, size, className, ...props }: ITextProps) {
+  return <p className={textVariants({ tone, size, className })}
+            {...props} />;
+}
+
+// ---- article blocks: lists and quotes ---------------------------------------------------------
+
+const listVariants = variants({
+  base: 'dui:text-foreground dui:pl-6 dui:space-y-1',
+  variants: {
+    ordered: {
+      true: 'dui:list-decimal',
+      false: 'dui:list-disc',
+    },
+  },
+  defaultVariants: { ordered: 'false' },
+});
+
+export interface IListProps extends HTMLAttributes<HTMLUListElement | HTMLOListElement> {
+  readonly ordered?: boolean;
+}
+
+export function List({ ordered = false, className, ...props }: IListProps) {
+  const Tag = ordered ? 'ol' : 'ul';
+  return <Tag className={listVariants({ ordered: ordered ? 'true' : 'false', className })}
+              {...(props)} />;
+}
+
+export function ListItem({ className, ...props }: HTMLAttributes<HTMLLIElement>) {
+  return <li className={cn('dui:text-base', className)}
+             {...props} />;
+}
+
+export interface IBlockquoteProps extends HTMLAttributes<HTMLQuoteElement> {
+  /** who said it — rendered as a footer line after the quoted blocks */
+  readonly cite?: string;
+}
+
+export function Blockquote({ cite, className, children, ...props }: IBlockquoteProps) {
+  return (
+    <blockquote className={cn('dui:border-l-4 dui:border-border dui:pl-4 dui:italic dui:text-muted-foreground dui:space-y-2', className)}
+                {...props}>
+      {children}
+      {cite ? <footer className="dui:not-italic dui:text-sm">— {cite}</footer> : null}
+    </blockquote>
+  );
+}

package/src/dockArrangement.ts

@@ -0,0 +1,212 @@
+// The dock ARRANGEMENT on the wire: the user's layout as a query-parameter-sized string, so the
+// address bar — not localStorage — carries it. An address survives a browser restart, a duplicated
+// tab, and travels to another person as a link; a localStorage blob does none of that, and its
+// shape is dockview's serialization model, not data. The format below is deliberately minimal —
+// rows and columns with tab names and percent sizes — and every character of it is legal RAW in a
+// URL query (RFC 3986), so nothing percent-encodes: the address stays exactly this readable.
+// Measured against deflate+base64url on real workbench strings the plain text is SHORTER
+// (~85 chars vs ~106): compression pays its header on strings this small, so there is none.
+//
+// Grammar (orientation alternates with depth; the root lays out COLUMNS unless it starts with
+// `-`, which flips it to rows):
+//
+//   arrangement = ["-"] item ("," item)* (";" reference)*
+//   item        = [size ":"] node          size — integer percent of the parent's axis;
+//                                          items without one split the remainder equally
+//   node        = "(" item ("," item)* ")" a nested branch (orientation flipped)
+//               | tab ("~" tab)*           ONE group: its tabs in row order
+//   tab         = name ["!"]               "!" — the group's front tab (default: the first)
+//   name        = authored-panel-id        e.g. `tree` — must not start with a digit or `_`
+//               | "_"                      a blank tab (the dock's empty content)
+//               | ordinal "*" ref-index    a component tab: its `component:N` ordinal and an
+//                                          index into the `;`-appended reference dictionary
+//
+// Example: `20:(60:tree,palette),(1*0!~2*0),settings;_ns_x_t_component_n_canvas_v_0_0_1`
+// — three columns: tree over palette (60/40) at 20% width, one group with two canvas tabs
+// (the first in front), and settings taking what remains.
+//
+// The parser is TOLERANT the way the address bar demands: a malformed tab is dropped, an emptied
+// group or branch dissolves, and a string with nothing left parses to null — the dock then builds
+// its default layout. Component-tab ordinals are preserved verbatim because other parameters key
+// on the `component:N` ids (the editor's ?canvas= does). Titles are NOT serialized: content that
+// cares names its own tab through the DockTab contract once it mounts.
+
+/** dynamic blank tabs live under this id prefix, outside the authored panel set */
+export const EMPTY_TAB_PREFIX = 'empty:';
+
+/** dynamic component tabs (opened by reference) live under this one */
+export const COMPONENT_TAB_PREFIX = 'component:';
+
+export interface IArrangedTab {
+  /** an authored panel id, `component:N`, or `empty:N` */
+  readonly id: string;
+  /** component tabs only: what the tab shows */
+  readonly reference?: string;
+  /** the group's front tab (serialized as `!` when it is not simply the first) */
+  readonly active?: boolean;
+}
+
+export interface IArrangedGroup {
+  readonly kind: 'group';
+  /** integer percent of the parent's axis; absent — an equal split of the remainder */
+  readonly sizePercent?: number;
+  readonly tabs: readonly IArrangedTab[];
+}
+
+export interface IArrangedBranch {
+  readonly kind: 'branch';
+  readonly sizePercent?: number;
+  readonly items: readonly TArrangedNode[];
+}
+
+export type TArrangedNode = IArrangedGroup | IArrangedBranch;
+
+export interface IArrangement {
+  /** the root lays out columns (true) or rows; orientation alternates with every nesting */
+  readonly horizontal: boolean;
+  readonly items: readonly TArrangedNode[];
+}
+
+const AUTHORED_ID = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const REFERENCE = /^[A-Za-z0-9_-]+$/;
+const COMPONENT_TAB = /^(\d+)\*(\d+)$/;
+const SIZE_PREFIX = /^(\d{1,2}):/;
+
+function tabText(tab: IArrangedTab, references: string[]): string | null {
+  const mark = tab.active ? '!' : '';
+  if (tab.id.startsWith(COMPONENT_TAB_PREFIX)) {
+    const ordinal = tab.id.slice(COMPONENT_TAB_PREFIX.length);
+    if (!/^\d+$/.test(ordinal) || !tab.reference || !REFERENCE.test(tab.reference)) return null;
+    const known = references.indexOf(tab.reference);
+    const index = known === -1 ? references.push(tab.reference) - 1 : known;
+    return `${ordinal}*${index}${mark}`;
+  }
+  if (tab.id.startsWith(EMPTY_TAB_PREFIX)) return `_${mark}`;
+  return AUTHORED_ID.test(tab.id) ? `${tab.id}${mark}` : null;
+}
+
+/** the items of one branch as text; recursion carries nesting, the LAST item never carries a size */
+function itemsText(items: readonly TArrangedNode[], references: string[]): string | null {
+  const texts = items
+    .map<{ node: TArrangedNode; text: string | null }>((node) => {
+      if (node.kind === 'branch') {
+        const inner = itemsText(node.items, references);
+        return { node, text: inner === null ? null : `(${inner})` };
+      }
+      const tabs = node.tabs
+        .map((tab) => tabText(tab, references))
+        .filter((text): text is string => text !== null);
+      return { node, text: tabs.length === 0 ? null : tabs.join('~') };
+    })
+    .filter((entry): entry is { node: TArrangedNode; text: string } => entry.text !== null);
+  if (texts.length === 0) return null;
+  return texts
+    .map(({ node, text }, index) => {
+      const size = node.sizePercent === undefined ? undefined : Math.round(node.sizePercent);
+      const last = index === texts.length - 1;
+      return !last && size !== undefined && size >= 1 && size <= 99 ? `${size}:${text}` : text;
+    })
+    .join(',');
+}
+
+/** `null` when there is nothing to say — the parameter should leave the address */
+export function serializeArrangement(arrangement: IArrangement): string | null {
+  const references: string[] = [];
+  const items = itemsText(arrangement.items, references);
+  if (items === null) return null;
+  const dictionary = references.map((reference) => `;${reference}`).join('');
+  return `${arrangement.horizontal ? '' : '-'}${items}${dictionary}`;
+}
+
+interface IParseState {
+  readonly references: readonly string[];
+  readonly taken: Set<string>;
+  emptySeq: number;
+}
+
+function parseTab(text: string, state: IParseState): IArrangedTab | null {
+  const active = text.endsWith('!');
+  const name = active ? text.slice(0, -1) : text;
+  const withActive = active ? { active: true } : {};
+  if (name === '_') {
+    state.emptySeq += 1;
+    return { id: `${EMPTY_TAB_PREFIX}${state.emptySeq}`, ...withActive };
+  }
+  const component = COMPONENT_TAB.exec(name);
+  if (component) {
+    const reference = state.references[Number(component[2])];
+    const id = `${COMPONENT_TAB_PREFIX}${Number(component[1])}`;
+    if (!reference || state.taken.has(id)) return null;
+    state.taken.add(id);
+    return { id, reference, ...withActive };
+  }
+  if (!AUTHORED_ID.test(name) || state.taken.has(name)) return null;
+  state.taken.add(name);
+  return { id: name, ...withActive };
+}
+
+/** split on `separator` at paren depth zero */
+function splitTop(text: string, separator: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (const char of text) {
+    if (char === '(') depth += 1;
+    else if (char === ')') depth = Math.max(0, depth - 1);
+    if (char === separator && depth === 0) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+  parts.push(current);
+  return parts.filter((part) => part.length > 0);
+}
+
+function balanced(text: string): boolean {
+  let depth = 0;
+  for (const char of text) {
+    if (char === '(') depth += 1;
+    else if (char === ')') {
+      depth -= 1;
+      if (depth < 0) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/** the items of one branch; recursion carries nesting, malformed items are dropped */
+function parseItems(text: string, state: IParseState): TArrangedNode[] | null {
+  const items = splitTop(text, ',').flatMap<TArrangedNode>((part) => {
+    const sized = SIZE_PREFIX.exec(part);
+    const sizePercent = sized ? Number(sized[1]) : undefined;
+    const body = sized ? part.slice(sized[0].length) : part;
+    const withSize = sizePercent !== undefined && sizePercent >= 1 ? { sizePercent } : {};
+    if (body.startsWith('(')) {
+      if (!body.endsWith(')') || !balanced(body)) return [];
+      const inner = parseItems(body.slice(1, -1), state);
+      if (inner === null) return [];
+      // a one-item wrapper is no branch at all — the item takes its place (and its size)
+      if (inner.length === 1) return [{ ...inner[0], ...withSize }];
+      return [{ kind: 'branch', ...withSize, items: inner }];
+    }
+    const tabs = body.split('~').flatMap((piece) => {
+      const tab = parseTab(piece, state);
+      return tab === null ? [] : [tab];
+    });
+    return tabs.length === 0 ? [] : [{ kind: 'group', ...withSize, tabs }];
+  });
+  return items.length === 0 ? null : items;
+}
+
+/** tolerant of hand-mangled addresses; `null` means "build the default layout" */
+export function parseArrangement(value: string | null): IArrangement | null {
+  if (!value) return null;
+  const [tree, ...references] = value.split(';');
+  if (!tree || references.some((reference) => !REFERENCE.test(reference))) return null;
+  const horizontal = !tree.startsWith('-');
+  const body = horizontal ? tree : tree.slice(1);
+  const items = parseItems(body, { references, taken: new Set<string>(), emptySeq: 0 });
+  return items === null ? null : { horizontal, items };
+}

package/src/dockLayout.ts

@@ -0,0 +1,139 @@
+// The DOCK LAYOUT CONTRACT: how content cooperates with a dock that hosts it — entirely OPTIONAL
+// on both sides. The dock (a @mosetta/ui-kit-react block) registers a DockLayout in the page's
+// DI container and hands each panel a scoped DockTab; content pulls them with `useDiOptional` and
+// simply does nothing when they are absent (rendered outside any dock, or inside a dock that
+// predates the contract). The contract lives HERE — in the shared base library — because DI
+// tokens match by INSTANCE: both the dock and its guests must import the very same dependency
+// artifact, and @mosetta/ui is the one library both already build against.
+//
+// A tab's CONTENT is a component reference, not a slot: the authored children of the dock are
+// only the offered first-visit layout, and any module may ask the dock to open any component —
+// which is how a page holding nothing but a dock and a blank-tab block winds itself up into a
+// full workbench, click by click, the layout (references included) persisting as a preference.
+//
+// The per-panel handles (DockTab, DockTabRow) travel through DI SCOPES: the dock registers each
+// handle in the panel's own scope, and content resolves it up the scope chain (useDiOptional) —
+// no wrapped containers anywhere on the way.
+import { SingleDiToken } from '@mosetta/di';
+
+export type TDockSide = 'left' | 'right' | 'bottom' | 'center';
+
+/** an open tab as the layout manager reports it */
+export interface IDockTabInfo {
+  readonly id: string;
+  readonly title: string;
+  /** the root reference of what the tab shows (an authored child's root, or the opened component) */
+  readonly reference?: string;
+  /** whatever the tab's content whispered about itself (setMeta) — e.g. the open draft id */
+  readonly meta: Readonly<Record<string, unknown>>;
+  /** the tab is the one its group shows */
+  readonly front?: boolean;
+}
+
+/** a panel of the AUTHORED first-visit set — what `open(id)` and the arrangement resolve first */
+export interface IDockOpenable {
+  readonly id: string;
+  readonly title: string;
+}
+
+/** a component to open as a tab — the reference IS the tab's identity for find-or-open */
+export interface IDockComponent {
+  readonly reference: string;
+  readonly title: string;
+  readonly settings?: Record<string, unknown>;
+}
+
+export interface IDockOpenOptions {
+  /** skip the find-by-reference dedupe: another INSTANCE of an already-open component */
+  readonly fresh?: boolean;
+  /** open as a tab of the group holding THIS tab (id), instead of the active group */
+  readonly beside?: string;
+}
+
+/**
+ * One wish of an arrangement: resolved in order — an OPEN tab by `id`, an open tab by
+ * `reference`, the authored set by `id`, and finally `reference` opens the component fresh at
+ * the wished side. A wish may carry only an `id` (authored sets), only a `reference`
+ * (bootstrap from nothing), or both.
+ */
+export interface IDockWant {
+  readonly id?: string;
+  readonly reference?: string;
+  readonly title?: string;
+  readonly dock?: TDockSide;
+  readonly settings?: Record<string, unknown>;
+}
+
+/**
+ * The dock's layout manager: a DI service proxying the dock's own view api. The dock component
+ * registers one instance per realm and re-attaches it on every re-mount; whoever needs to drive
+ * the layout resolves it optionally and stays functional without it.
+ */
+export abstract class DockLayout {
+  /** bring an AUTHORED panel forward by its id; a closed one is re-created at its declared side */
+  abstract open(id: string): void;
+
+  /** find a tab showing this component (activate), or open it as a fresh tab; returns the tab id */
+  abstract openComponent(component: IDockComponent, options?: IDockOpenOptions): string | null;
+
+  /** the offered arrangement: the primary beside the widest group, companions in their columns */
+  abstract arrange(primary: IDockWant, companions?: readonly IDockWant[]): void;
+
+  /** activate an OPEN tab by its id (see tabs()) */
+  abstract activate(tabId: string): void;
+
+  /**
+   * Name an OPEN tab by its id. Content usually names its own tab (DockTab), but an INACTIVE
+   * address-restored tab never mounts its content — whoever restores it says what it holds.
+   */
+  abstract rename(tabId: string, title: string): void;
+
+  /** every open tab with its content-reported meta */
+  abstract tabs(): IDockTabInfo[];
+
+  /** the AUTHORED panel set — what `open(id)` can resolve without a reference */
+  abstract openable(): IDockOpenable[];
+
+  /** fires on every layout change (tabs opened/closed/moved); returns the unsubscribe */
+  abstract onDidChange(listener: () => void): () => void;
+}
+
+export const DOCK_LAYOUT_TOKEN = new SingleDiToken<DockLayout>('DOCK_LAYOUT_TOKEN');
+
+/**
+ * The CURRENT TAB, scoped to a panel's content: the dock provides one per panel, so a module
+ * can name its own tab after what it shows and report identity meta for tabs() lookups.
+ */
+export abstract class DockTab {
+  abstract readonly id: string;
+
+  abstract rename(title: string): void;
+
+  /** merge identity facts about the content (e.g. { editingDraftId }) into the tab's meta */
+  abstract setMeta(meta: Record<string, unknown>): void;
+
+  /** fires when THIS tab becomes the active one of its group; returns the unsubscribe */
+  abstract onDidActivate(listener: () => void): () => void;
+
+  /**
+   * Whether this tab is the one its group shows RIGHT NOW. A host that keeps every tab mounted
+   * (the workbench shell) answers it so content mounting behind the front tab does not act as
+   * if it were in front; a host that cannot say leaves it undefined, and content assumes it is.
+   */
+  front?(): boolean;
+}
+
+export const DOCK_TAB_TOKEN = new SingleDiToken<DockTab>('DOCK_TAB_TOKEN');
+
+/**
+ * The TAB ROW a header-slotted control renders in (one instance per group): lets a "new tab"
+ * button open things as tabs of ITS OWN row rather than at a declared side.
+ */
+export abstract class DockTabRow {
+  abstract openHere(id: string): void;
+
+  /** a FRESH tab in this row, rendering the dock's empty content — a blank page to start from */
+  abstract openEmpty(): void;
+}
+
+export const DOCK_TAB_ROW_TOKEN = new SingleDiToken<DockTabRow>('DOCK_TAB_ROW_TOKEN');