@selimssevgi/cube-design-angular 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selimssevgi/cube-design-angular",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "cube design in angular: the pieces anlat, mosaic and cubes share, starting with the isometric cube picture.",
   "keywords": [
     "angular",

package/tokens/dark.css

@@ -1,5 +1,5 @@
 /*
- * cube design's dark dialect (mosaic; cube design `07-visual.md`): black plastic with one light
+ * cube design's dark dialect (mosaic; cube design `04-screens.md`): black plastic with one light
  * source. import it once in an app's global styles, or set the same variables yourself.
  */
 :root {
@@ -32,6 +32,13 @@
   --cube-context-line-size: 13px;
   --cube-context-title-lines: 2;
   --cube-context-line-lines: 2;
+  --cube-context-go: #374151;
+  /* the carry (cubeCarry): the ghost that follows the finger, the piece left behind */
+  --cube-carry-ghost-transform: scale(1.08) rotate(-2deg);
+  --cube-carry-ghost-shadow: 0 14px 32px rgb(0 0 0 / 0.5);
+  --cube-carry-ghost-opacity: 0.95;
+  --cube-carry-ghost-z: 1000;
+  --cube-carry-lifted-opacity: 0.3;
   --cube-square-place: color-mix(in srgb, #4b5563 55%, transparent);
   --cube-square-place-dashed: #4b5563;
   --cube-square-place-width: 1.5px;
@@ -39,4 +46,7 @@
   --cube-square-gap-scale: 1;
   --cube-square-edge: color-mix(in srgb, #7dd3fc 45%, transparent);
   --cube-square-focus: #7dd3fc;
+  /* something on its way (<cube-loading>) */
+  --cube-loading-place: rgba(156, 163, 175, 0.1);
+  --cube-loading-gap: 12px;
 }

package/tokens/light.css

@@ -1,5 +1,5 @@
 /*
- * cube design's light dialect (cubes, anlat; cube design `07-visual.md`): import it once in an
+ * cube design's light dialect (cubes, anlat; cube design `04-screens.md`): import it once in an
  * app's global styles, or set the same variables yourself.
  */
 :root {
@@ -32,6 +32,13 @@
   --cube-context-line-size: 13px;
   --cube-context-title-lines: 2;
   --cube-context-line-lines: 2;
+  --cube-context-go: #edf0ec;
+  /* the carry (cubeCarry): the ghost that follows the finger, the piece left behind */
+  --cube-carry-ghost-transform: scale(1.08) rotate(-2deg);
+  --cube-carry-ghost-shadow: 0 14px 32px rgb(31 42 38 / 0.22);
+  --cube-carry-ghost-opacity: 0.95;
+  --cube-carry-ghost-z: 1000;
+  --cube-carry-lifted-opacity: 0.3;
   --cube-square-place: color-mix(in srgb, #dae0d9 55%, transparent);
   --cube-square-place-dashed: #dae0d9;
   --cube-square-place-width: 1.5px;
@@ -39,4 +46,7 @@
   --cube-square-gap-scale: 1;
   --cube-square-edge: color-mix(in srgb, #5f9a80 45%, transparent);
   --cube-square-focus: #5f9a80;
+  /* something on its way (<cube-loading>) */
+  --cube-loading-place: #e3e7e1;
+  --cube-loading-gap: 12px;
 }

package/types/selimssevgi-cube-design-angular.d.ts

@@ -5,7 +5,7 @@ import { InjectionToken, TemplateRef } from "@angular/core";
  * n × n stickers. a sticker is coloured by a piece, or pale while nothing is known for it.
  *
  * the same projection anlat, mosaic and cubes drew by hand before this package (cube design,
- * `07-visual.md`). pure functions, no angular: they can be used anywhere.
+ * `04-screens.md`). pure functions, no angular: they can be used anywhere.
  */
 /** The side of the smallest cube that holds this many pieces, up to 7 × 7 × 7. */
 export declare function sizeFor(count: number): number;
@@ -167,6 +167,232 @@ export declare class CubeHold {
     "cubeHeld": "cubeHeld";
   }, never, never, true, never>;
 }
+/** what a pinch reports: which way the fingers went, where, how it came and the event that ended it. */
+export interface CubePinched {
+  /** `in`: fingers apart, going into the piece under them; `out`: fingers together, one level out. */
+  way: 'in' | 'out';
+  /** the element under the pinch (between two fingers, under the pointer); null when none. */
+  at: Element | null;
+  /**
+   * `touch`: two fingers on a screen; `wheel`: ctrl and the wheel, which is how chrome, edge and
+   * firefox send a trackpad's pinch; `gesture`: safari's own gesture events for a trackpad's pinch.
+   */
+  via: 'touch' | 'wheel' | 'gesture';
+  /** the event that decided it: the `pointerup`, the first `wheel` of the stream, the `gestureend`. */
+  event: Event;
+}
+/** two fingers this much further apart than they started is a pinch in (cubes', mosaic's, anlat's). */
+export declare const CUBE_PINCH_APART = 1.25;
+/** two fingers this much closer than they started is a pinch out. */
+export declare const CUBE_PINCH_TOGETHER = 0.8;
+/**
+ * a trackpad's pinch is a stream of ctrl + wheel events for as long as the fingers move; the stream
+ * is one gesture until the wheel has been quiet this long, in milliseconds (mosaic's, 3 nov 2026).
+ */
+export declare const CUBE_WHEEL_QUIET_MS = 250;
+/**
+ * whether a ctrl + wheel event at `now` starts a new gesture, given when the last one of the stream
+ * came (`-Infinity` for never). pure, so an app with a wheel of its own (a puzzle, a canvas) keeps
+ * the same rule.
+ */
+export declare function startsWheelGesture(lastAt: number, now: number, quietMs?: number): boolean;
+/**
+ * the pinch (principle 25, two fingers together is one level out): fingers apart on a piece raise
+ * one `cubePinched` with `way: 'in'`, fingers together one with `way: 'out'`. on a computer a
+ * trackpad's pinch or ctrl and the wheel do the same, one level for one pinch however long it lasts.
+ *
+ * it only reports. it never routes or zooms: what `in` opens (most often a tap on the tile at `at`)
+ * and where `out` goes (the way i came) stay in the app. it keeps the browser's own page zoom away
+ * from a ctrl + wheel and a safari gesture on its element, and lets every other event through.
+ */
+export declare class CubePinch {
+  /** no pinch at all: the listeners do nothing and the browser zooms the page again. */
+  readonly cubePinchDisabled: import("@angular/core").InputSignal<boolean>;
+  /** how quiet the wheel must be before a new pinch starts, in milliseconds. */
+  readonly cubePinchQuietMs: import("@angular/core").InputSignal<number>;
+  /** the fingers went apart (`in`) or together (`out`): once a pinch. */
+  readonly cubePinched: import("@angular/core").OutputEmitterRef<CubePinched>;
+  constructor();
+  /** the pointers down on the element, by id, with where each is now. */
+  private readonly pointers;
+  /** a two-finger pinch under way: how far apart the fingers started and what was between them. */
+  private pinch;
+  protected down(e: PointerEvent): void;
+  protected move(e: PointerEvent): void;
+  /** the first finger to lift decides; the second has nothing left to say. */
+  protected up(e: PointerEvent): void;
+  protected cancel(e: PointerEvent): void;
+  protected wheel(e: WheelEvent): void;
+  protected gestureStart(e: Event): void;
+  protected gestureChange(e: Event): void;
+  /** safari decides at the end of its gesture; a wheel stream that already decided wins. */
+  protected gestureEnd(e: Event): void;
+  private emit;
+  static ɵfac: i0.ɵɵFactoryDeclaration<CubePinch, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<CubePinch, "[cubePinch]", never, {
+    "cubePinchDisabled": {
+      "alias": "cubePinchDisabled";
+      "required": false;
+      "isSignal": true;
+    };
+    "cubePinchQuietMs": {
+      "alias": "cubePinchQuietMs";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "cubePinched": "cubePinched";
+  }, never, never, true, never>;
+}
+/** the `data-drop` value of the element that means out: one level up (the app's ‹). */
+export declare const CUBE_DROP_OUT = "out";
+/** how far a lifted piece must travel before letting go is a drop, not a hold, in pixels. */
+export declare const CUBE_CARRY_MOVE = 12;
+/** a piece lifted: the press was held, and it may now be carried. */
+export interface CubeLifted {
+  /** the carried piece, as `[cubeCarry]` names it. */
+  piece: string;
+  /** the element holding the directive (the tile left behind, faded). */
+  element: HTMLElement;
+  /** the ghost following the finger: a copy of the element, on `document.body`. */
+  ghost: HTMLElement;
+}
+/** what the carried piece is over now: a `[data-drop]` element, or nothing. */
+export interface CubeCarriedOver {
+  piece: string;
+  /** its `data-drop`, `'out'` for the ‹; null when over nothing a piece may land on. */
+  onto: string | null;
+  /** the `[data-drop]` element it is over, marked meanwhile; null over nothing. */
+  target: HTMLElement | null;
+}
+/** a carried piece let go over a `[data-drop]` element. */
+export interface CubeDropped {
+  piece: string;
+  /** the target's `data-drop`: a piece's key, or `'out'` (`CUBE_DROP_OUT`) for the ‹. */
+  onto: string;
+  /** the element it was let go over. */
+  target: HTMLElement;
+}
+/**
+ * how a carry ended: `dropped` (on a target), `held` (let go without moving: a hold), `nowhere`
+ * (let go over nothing a piece lands on: it goes back), `cancelled` (two fingers, escape, a
+ * cancelled touch, or the directive went away).
+ */
+export type CubeCarryEnd = 'dropped' | 'held' | 'nowhere' | 'cancelled';
+/** the classes and attributes the carry puts on the page while it carries; the app styles them. */
+export declare const CUBE_CARRY_CLASSES: {
+  /** on `document.body` while a piece is lifted. */
+  readonly carrying: "cube-carrying";
+  /** on the lifted piece's own element, which stays where it was. */
+  readonly lifted: "cube-carry-lifted";
+  /** on the ghost that follows the finger. */
+  readonly ghost: "cube-carry-ghost";
+  /** on the `[data-drop]` element the piece is over. */
+  readonly over: "cube-carry-over";
+};
+/**
+ * carry and drop (selim, 3 november 2026, the grouping prototype's round 2): press and hold a piece,
+ * and it lifts; carry it onto another piece and let go, and the app asks what the drop means (drop
+ * it in, make them one). a hold that does not move is still a hold (`cubeHeld`, the context cube),
+ * a tap stays a tap, and two fingers (a pinch) cancel.
+ *
+ * it holds as `cubeHold` does (`cubeHeld`, the same `CubeHeld`), so it replaces `cubeHold` on a
+ * piece that can be carried: put one of the two on an element, never both. what it adds: at the
+ * hold time (520 ms) the piece lifts, and a ghost of it follows the finger; the `[data-drop]`
+ * element under the finger is marked; letting go there emits `cubeDropped` with `{ piece, onto }`,
+ * where `onto` is that element's `data-drop` (`'out'` for the app's ‹). letting go without moving
+ * the piece is the hold, said then. with `[cubeCarry]` empty (null or '') nothing lifts and it is
+ * `cubeHold`: the hold is said at the hold time.
+ *
+ * mouse and touch both: touch events on a phone, as the prototype (pointer events lose the finger
+ * to the page's scroll), the mouse's own events elsewhere. it says no words and draws only the
+ * ghost; the hint, the sheet and the marks' look are the app's.
+ */
+export declare class CubeCarry {
+  /** the piece this element carries (its key, as the app's `data-drop` names pieces); empty: none. */
+  readonly cubeCarry: import("@angular/core").InputSignal<string | null | undefined>;
+  /** no hold and no carry: the listeners do nothing and the browser's own menu stays. */
+  readonly cubeCarryDisabled: import("@angular/core").InputSignal<boolean>;
+  /** how long a press is held before it lifts (or holds), in milliseconds. */
+  readonly cubeHoldMs: import("@angular/core").InputSignal<number>;
+  /** how far the press may move before the hold time and still hold, in pixels. */
+  readonly cubeHoldSlop: import("@angular/core").InputSignal<number>;
+  /** a short buzz when it lifts or holds, where the device can. */
+  readonly cubeHoldBuzz: import("@angular/core").InputSignal<boolean>;
+  /** a hold: let go without moving after the hold time, a right click or the menu key. */
+  readonly cubeHeld: import("@angular/core").OutputEmitterRef<CubeHeld>;
+  /** the piece lifted at the hold time; the app shows its hint and names its ‹ the way out. */
+  readonly cubeLifted: import("@angular/core").OutputEmitterRef<CubeLifted>;
+  /** the piece is over another `[data-drop]` element now, or over none. */
+  readonly cubeCarriedOver: import("@angular/core").OutputEmitterRef<CubeCarriedOver>;
+  /** the piece was let go over a `[data-drop]` element. */
+  readonly cubeDropped: import("@angular/core").OutputEmitterRef<CubeDropped>;
+  /** a lift ended, however it ended: the app takes its hint away. after `cubeDropped` or `cubeHeld`. */
+  readonly cubeCarryEnd: import("@angular/core").OutputEmitterRef<CubeCarryEnd>;
+  private readonly element;
+  private press;
+  private lastTouch;
+  /** the click after a hold or a carry is swallowed, so the piece does not also open. */
+  protected swallow: boolean;
+  private readonly doc;
+  private readonly listening;
+  constructor();
+  /** whether a piece is being carried (lifted) by this element now. */
+  get carrying(): boolean;
+  protected touchStart(e: TouchEvent): void;
+  protected mouseDown(e: MouseEvent): void;
+  /** a right click, the menu key or shift+f10 hold at once; a phone's own long press is ours. */
+  protected menu(e: Event): void;
+  /** the browser's own drag of a link or a picture would take the mouse away from the carry. */
+  protected noDrag(e: Event): void;
+  private begin;
+  private touchMove;
+  private touchEnd;
+  private lift;
+  private moveTo;
+  private end;
+  /** two fingers, escape, a cancelled touch: whatever was lifted goes back, nothing is said but the end. */
+  cancel(): void;
+  private clean;
+  /** the press is over: its timer and the page's listeners go. */
+  private forget;
+  private listen;
+  private fireHeld;
+  static ɵfac: i0.ɵɵFactoryDeclaration<CubeCarry, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<CubeCarry, "[cubeCarry]", never, {
+    "cubeCarry": {
+      "alias": "cubeCarry";
+      "required": false;
+      "isSignal": true;
+    };
+    "cubeCarryDisabled": {
+      "alias": "cubeCarryDisabled";
+      "required": false;
+      "isSignal": true;
+    };
+    "cubeHoldMs": {
+      "alias": "cubeHoldMs";
+      "required": false;
+      "isSignal": true;
+    };
+    "cubeHoldSlop": {
+      "alias": "cubeHoldSlop";
+      "required": false;
+      "isSignal": true;
+    };
+    "cubeHoldBuzz": {
+      "alias": "cubeHoldBuzz";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "cubeHeld": "cubeHeld";
+    "cubeLifted": "cubeLifted";
+    "cubeCarriedOver": "cubeCarriedOver";
+    "cubeDropped": "cubeDropped";
+    "cubeCarryEnd": "cubeCarryEnd";
+  }, never, never, true, never>;
+}
 /** the views a cube can be shown in, each drawn as its own shape. */
 export type CubeIconView = 'square' | 'one' | 'two' | 'three' | 'four' | 'grid-4x5' | 'grid-3x6';
 /** what a tile of a cube the app keeps is about (a context cube's parts and their choices). */
@@ -227,17 +453,131 @@ export type Direction = 'up' | 'down';
 /** what an item is sorted by: text, a number, or nothing found (not known yet). */
 export type SortValue = string | number | null | undefined;
 /**
- * items in the order a sort asks for. `by` reads what each item is sorted by; text is compared as
- * a person reads it, numbers as numbers. an item with nothing found is not known yet and comes last
- * in both directions (empty is the point, never hidden). ties keep the items' own order.
+ * how text is compared: `natural` reads numbers inside text as numbers (`moment 2` before
+ * `moment 10`), as a person reads them; `plain` compares letter by letter (`moment 10` first).
+ * both are kept: natural is the default, an app may offer plain (decision of 2026-11-02).
  */
-export declare function sortItems<T>(items: readonly T[], by: (item: T) => SortValue, dir: Direction): T[];
+export type TextOrder = 'natural' | 'plain';
+/** the ways text can be compared, the default first. */
+export declare const TEXT_ORDERS: readonly TextOrder[];
 /**
- * the parts a context cube can have. the seven are the ones cubes found; an app may add its own,
- * any string, and they come after the known ones.
+ * items in the order a sort asks for. `by` reads what each item is sorted by; numbers are compared
+ * as numbers, text in the reader's language, numbers inside it as numbers (`text`, natural by
+ * default; `plain` compares letter by letter). an item with nothing found (empty text, `NaN`) is
+ * not known yet and comes last in both directions (empty is the point, never hidden). ties keep
+ * the items' own order.
+ */
+export declare function sortItems<T>(items: readonly T[], by: (item: T) => SortValue, dir: Direction, text?: TextOrder): T[];
+/** what an app gives for where: its places and how they hold each other, from its own world. */
+export interface WhereSource {
+  /** the place everything stands in at last: the top (mine, mosaic, my to-dos). */
+  readonly top: string;
+  /** what stands in a place, in its order, hidden ones too (they still count for loops). */
+  partsOf(place: string): readonly string[];
+  /** every place a piece stands in now (its live rows). */
+  placesOf(piece: string): readonly string[];
+  /** a place's name as the app shows it (data, not a word of the package). */
+  nameOf(place: string): string;
+  /** the place the app put it in, which it never leaves; none by default. */
+  givenPlaceOf?(piece: string): string | null;
+  /** left out of a level (hidden there); nothing by default. */
+  hidden?(id: string): boolean;
+  /**
+   * why the piece may not stand in the place, by the app's own rules (a screen that holds nothing,
+   * a given piece into another given one), as the app's refusal key; null when it may. the package
+   * checks "inside itself" on its own first.
+   */
+  refuses?(piece: string, place: string): string | null;
+}
+/** the refusals the package finds by itself; every other one is the app's (`WhereSource.refuses`). */
+export type WhereRefusal = 'inside-itself' | 'given-place' | 'last-place' | (string & {});
+/** one place, as a where level shows it. the words for it are the app's. */
+export interface CubePlace {
+  /** the place's key, as the app's source knows it. */
+  key: string;
+  /** its name, from the source's `nameOf`. */
+  title: string;
+  /** the place this level looks inside, listed first ("mosaic, the top", "kitchen itself"). */
+  at: boolean;
+  /** the top, the place everything stands in at last. */
+  top: boolean;
+  /** the held piece stands here (ticked). */
+  in: boolean;
+  /** here is its only place: it never leaves it. */
+  last: boolean;
+  /** the app put it here: it never leaves it. */
+  given: boolean;
+  /** the held piece itself, listed pale where it stands among the others. */
+  self: boolean;
+  /** a place inside the held piece, listed pale: standing there would put it inside itself. */
+  inside: boolean;
+  /** what a tap asks for: stand it here too, or take it out of here; null for itself or inside it. */
+  tap: 'stand' | 'take-out' | null;
+  /** why that tap would be refused, or null when it would be done. */
+  refused: WhereRefusal | null;
+  /** what is shown in it now, the held piece left out, in order: for the app's line. */
+  holds: string[];
+  /** nothing shown in it yet but the held piece. */
+  empty: boolean;
+  /** inside it are places worth looking into (›): it can stand somewhere in there. */
+  deeper: boolean;
+}
+/** how `placesOf` lists: one level, as the prototype (the default), or every place at once. */
+export interface PlacesOptions {
+  /** the place to look inside; the source's top by default. */
+  at?: string;
+  /**
+   * every place it could stand in or stands in, under `at`, as one list (cubes' and the todarch
+   * cube's flat list): no ›, and itself and what is inside it are left out instead of pale.
+   */
+  flat?: boolean;
+}
+/** everything standing inside a piece, at any depth and through every place (never the piece). */
+export declare function insideOf(source: WhereSource, piece: string): Set<string>;
+/** standing the piece in the place would put it inside itself (the place is it, or inside it). */
+export declare function wouldLoop(source: WhereSource, piece: string, place: string): boolean;
+/**
+ * why the piece may not stand in the place: `inside-itself`, or the app's own refusal; null when
+ * it may. a place it already stands in is never refused.
+ */
+export declare function refusalOf(source: WhereSource, piece: string, place: string): WhereRefusal | null;
+/**
+ * the places the held piece could stand in, as one level of where: the place looked inside (`at`,
+ * the top by default) first when it may stand there, then what stands in it, in its order, each
+ * place it could stand in or stands in, or that has such places deeper inside (`deeper`, ›); the
+ * held piece and what is inside it come pale (`self`, `inside`). with `flat`, every such place under
+ * `at` at once, breadth first, with no › and nothing pale.
+ *
+ * a tap on a place it stands in takes it out, refused on its given place and on its last; a tap on
+ * one it does not stand in stands it there too, refused when inside itself or by the app's rules.
+ */
+export declare function placesOf(source: WhereSource, held: string, opts?: PlacesOptions): CubePlace[];
+/** the words of where, the app's: a place's title and line (both from the place). */
+export interface WhereWords {
+  /** its title; the place's name by default (the app says "mosaic, the top", "kitchen itself"). */
+  title?(place: CubePlace): string;
+  /** the line under it: where the app put it, what it holds, itself, inside it. */
+  line?(place: CubePlace): string | null;
+}
+/**
+ * where as context tiles: every place, ticked (`inUse`) where it stands; pale where a tap can do
+ * nothing (itself, inside it, a place it may not stand in). each tile's `data` is its `CubePlace`,
+ * so the app's `pick` reads `tap` and `refused`, and a place with `deeper` gets `zoom`, the path that
+ * looks inside it (`['where', key]` by default), which `<cube-context>` draws as a ›. the words are
+ * the app's: `ContextWords.where`.
+ */
+export declare function whereLevel(places: readonly CubePlace[], words?: WhereWords, opts?: {
+  pathOf?: (place: CubePlace) => string[];
+}): ContextTile<CubePlace>[];
+/**
+ * the parts a context cube can have. the seven are the ones cubes found, and where (one piece in
+ * many places, 0.3.0); an app may add its own, any string, and they come after the known ones.
+ */
+export type ContextPartKey = 'names' | 'change' | 'view' | 'sort' | 'move' | 'where' | 'whose' | 'hide' | (string & {});
+/**
+ * cubes' rows: how it is called (names, change), how it is shown (view, sort), what i do with it
+ * (move, where, whose, hide).
  */
-export type ContextPartKey = 'names' | 'change' | 'view' | 'sort' | 'move' | 'whose' | 'hide' | (string & {});
-/** cubes' rows: how it is called (names, change), how it is shown (view, sort), what i do with it. */
 export declare const CONTEXT_PART_ORDER: readonly ContextPartKey[];
 /** the parts in their rows; parts an app added come last, in the order it gave them. twice is once. */
 export declare function orderParts(parts: readonly ContextPartKey[]): ContextPartKey[];
@@ -257,6 +597,14 @@ export interface ContextTile<D = unknown> {
   adds?: boolean;
   /** what the tile stands for, for the app's own `pick`. */
   data?: D;
+  /**
+   * a way inside it beside the tap (›): the path `<cube-context>` enters when the › is pressed,
+   * while a tap on the tile still asks the source's `pick` (where: a tap stands it there, › looks
+   * inside). none by default.
+   */
+  zoom?: string[] | null;
+  /** the ›'s label for a screen reader, the app's words; the tile's title by default. */
+  zoomLabel?: string | null;
 }
 /** where in the context cube one is: [] is its top (its parts), ['names'] a part, ['sort', by] deeper. */
 export type ContextPath = readonly string[];
@@ -317,6 +665,8 @@ export interface ContextWords {
   };
   /** said on the one in use, when the app wants it said. */
   inUse?: string;
+  /** where's title and line for each place (`whereLevel`); the place's name and no line without. */
+  where?: WhereWords;
 }
 /** the app's source of context cubes. */
 export declare const CONTEXT_CUBE_SOURCE: InjectionToken<ContextCubeSource<any>>;
@@ -330,7 +680,8 @@ export interface PartNow {
 /**
  * the icon a part's tile shows when the app gives none of what it holds now. most parts are drawn
  * by their own name; hide has no icon of its own and shows shown (the eye), since a piece is in
- * sight until it is hidden. an app passes `now.hide.icon` (`shown` or `hidden`) to say which.
+ * sight until it is hidden. an app passes `now.hide.icon` (`shown` or `hidden`) to say which. where
+ * is drawn as a place.
  */
 export declare const PART_ICONS: Partial<Record<ContextPartKey, string>>;
 /** the top of a context cube: its parts in rows, each with its word and, when given, what it holds now. */
@@ -665,6 +1016,12 @@ export declare class CubeContext {
   readonly words: import("@angular/core").InputSignal<ContextWords | null>;
   /** the largest side the square takes on a wide screen, in px. */
   readonly maxSide: import("@angular/core").InputSignal<number>;
+  /**
+   * what keeps the held thing the same thing while a pick is answered (itself by default). an app
+   * whose store gives a new object when the pick changes it (a rename, a hide) passes its id here, or
+   * the answer would be dropped as if the person had walked to another thing.
+   */
+  readonly heldKey: import("@angular/core").InputSignal<(held: unknown) => unknown>;
   /** walk into a deeper level: the app puts this path in its own route. */
   readonly enter: import("@angular/core").OutputEmitterRef<string[]>;
   /** step one level out (or out of the context cube, from its top). */
@@ -693,6 +1050,8 @@ export declare class CubeContext {
   protected readonly inUseWord: import("@angular/core").Signal<string | null>;
   protected readonly iconOf: typeof contextIcon;
   constructor();
+  /** the › of a tile with a way inside: walks into its path, without asking the source. */
+  protected zoomInto(tile: ContextTile, element?: HTMLElement): void;
   protected tap(tile: ContextTile, element?: HTMLElement): Promise<void>;
   static ɵfac: i0.ɵɵFactoryDeclaration<CubeContext, never>;
   static ɵcmp: i0.ɵɵComponentDeclaration<CubeContext, "cube-context", never, {
@@ -721,6 +1080,11 @@ export declare class CubeContext {
       "required": false;
       "isSignal": true;
     };
+    "heldKey": {
+      "alias": "heldKey";
+      "required": false;
+      "isSignal": true;
+    };
   }, {
     "enter": "enter";
     "out": "out";
@@ -747,4 +1111,102 @@ export interface TurningRows<T> {
 }
 /** the sides of one row: its front and the three behind it. */
 export declare const TURNING_SIDES = 4;
-export declare function turningRows<T>(pieces: readonly T[], own: T | null, cols?: number, rows?: number): TurningRows<T>;
+export declare function turningRows<T>(pieces: readonly T[], own: T | null, cols?: number, rows?: number): TurningRows<T>;
+/**
+ * something on its way, the cube design way: the cube picture's pale stickers take colour (a page,
+ * a cube) or its colours turn round the stickers (a piece: a tile, a button saving). picked by selim
+ * on 3 november 2026 (cube design's `08-decisions.md`, the study `studies/loading-pieces.md`), in
+ * place of grey pulsing cards and primeng's ring. it says no word: the app's own line is projected.
+ */
+/**
+ * the ways something on its way is shown. `fill`: the picture's pale stickers take colour one by
+ * one, then start again (a page or a cube). `turn`: the colours turn round the stickers, the way
+ * `rot` turns a cube (a piece). the places wait and the cube grows (the study's b and d) are not in
+ * yet: options to add when an app asks.
+ */
+export type CubeLoadingWay = 'fill' | 'turn';
+export declare const CUBE_LOADING_WAYS: readonly CubeLoadingWay[];
+/**
+ * how much is on its way. `page`: a whole screen, the picture over the line and the square's pale
+ * places. `cube`: a part of a screen, the picture over the line. `piece`: a tile or a button, a small
+ * cube beside the line, on one line with the words around it.
+ */
+export type CubeLoadingLevel = 'page' | 'cube' | 'piece';
+export declare const CUBE_LOADING_LEVELS: readonly CubeLoadingLevel[];
+/** the way picked for each level (selim, 3 november 2026): a page or a cube fills, a piece turns. */
+export declare function loadingWayFor(level: CubeLoadingLevel): CubeLoadingWay;
+/** how long one step lasts, in milliseconds: the prototype's pace. */
+export declare const CUBE_LOADING_STEP_MS: Readonly<Record<CubeLoadingWay, number>>;
+/** the picture's width for each level, in pixels, when the app sets none. */
+export declare const CUBE_LOADING_WIDTH: Readonly<Record<CubeLoadingLevel, number>>;
+/** the colours the stickers take when the app gives none: cube design's sample palette. */
+export declare const CUBE_LOADING_COLOURS: readonly string[];
+/** the picture is a 2 × 2 × 2 cube: three faces of four stickers. */
+export declare const CUBE_LOADING_STICKERS = 12;
+/**
+ * the stickers' colours at a step of a way (null is pale). `fill`: the first `step` stickers are
+ * coloured, all twelve, then none again. `turn`: every third sticker coloured, moved on one sticker
+ * a step. with no palette every sticker is pale.
+ */
+export declare function loadingStickers(way: CubeLoadingWay, step: number, palette?: readonly string[], stickers?: number): (string | null)[];
+/** the step drawn when nothing may move (reduced motion): half filled, or the turn at rest. */
+export declare function stillStep(way: CubeLoadingWay, stickers?: number): number;
+/**
+ * `<cube-loading>`: something on its way. the app projects its own line ("bringing my recipes…")
+ * and, when it failed, its own retry (`[cubeLoadingRetry]`). it is never red: a failed load is the
+ * picture at rest, pale, over the app's words.
+ */
+export declare class CubeLoading {
+  /** how much is on its way: a page (the default), a cube or a piece. */
+  readonly level: import("@angular/core").InputSignal<CubeLoadingLevel>;
+  /** the way it is shown; null is the one picked for its level (`loadingWayFor`). */
+  readonly way: import("@angular/core").InputSignal<CubeLoadingWay | null>;
+  /** how many places the square on a page has: its pale places, a complete square. 0 draws none. */
+  readonly count: import("@angular/core").InputSignal<number>;
+  /** it did not come: the picture rests, pale; the line is the app's and its retry is projected. */
+  readonly failed: import("@angular/core").InputSignal<boolean>;
+  /** the colours the stickers take; cube design's sample palette when not set. */
+  readonly colours: import("@angular/core").InputSignal<readonly string[]>;
+  /** the picture's width in pixels; null is its level's (`CUBE_LOADING_WIDTH`). */
+  readonly width: import("@angular/core").InputSignal<number | null>;
+  protected readonly wayInUse: import("@angular/core").Signal<CubeLoadingWay>;
+  protected readonly widthInUse: import("@angular/core").Signal<number>;
+  protected readonly places: import("@angular/core").Signal<number[]>;
+  private readonly step;
+  private readonly still;
+  protected readonly stickers: import("@angular/core").Signal<(string | null)[]>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<CubeLoading, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<CubeLoading, "cube-loading", never, {
+    "level": {
+      "alias": "level";
+      "required": false;
+      "isSignal": true;
+    };
+    "way": {
+      "alias": "way";
+      "required": false;
+      "isSignal": true;
+    };
+    "count": {
+      "alias": "count";
+      "required": false;
+      "isSignal": true;
+    };
+    "failed": {
+      "alias": "failed";
+      "required": false;
+      "isSignal": true;
+    };
+    "colours": {
+      "alias": "colours";
+      "required": false;
+      "isSignal": true;
+    };
+    "width": {
+      "alias": "width";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, ["*", "[cubeLoadingRetry]"], true, never>;
+}