yugoo-design 0.1.2 → 0.2.2

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: whiteboard
+description: Draw and revise a topic-based freeform whiteboard with the user. Use text, shapes and connectors to explore or explain ideas; do not substitute a sketch for an explicitly requested formal BPMN, page prototype or other Bundle output.
+---
+
+# Freeform whiteboards
+
+For canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+One topic is one editable board. The user and Agent edit the same scene file;
+there is no separate AI graph, screenshot authority or server-owned whiteboard.
+Choose the simplest arrangement that communicates the user's idea. Preserve
+uncertainties as uncertainties rather than inventing confirmed product facts.
+
+Read [reference/artifact-contract.md](reference/artifact-contract.md) before
+writing. Inspect the existing index and relevant scenes first. Preserve topic,
+element and binding IDs, unaffected positions, text, styling and image refs.
+A rename changes the title, not the identity or artifact path. A local revision
+does not authorize clearing or redrawing the entire scene. Read current files
+again before replacing an artifact that may have been edited meanwhile.
+
+The Producer draws directly using ordinary file tools. No special whiteboard
+tool, mandatory Worker, external drawing service or new runtime is required.
+
+Before creating a diagram or substantially rearranging one, read
+[reference/drawing-method.md](reference/drawing-method.md). Choose a visual
+structure from the relationships the user wants to understand, not from the
+available shapes. Briefly state the intended reading order and scope, then draw;
+do not add a confirmation gate for routine visual choices. For a local edit,
+retain the established visual structure unless the requested change needs more.
+Ask only when a missing decision materially changes meaning; otherwise show an
+editable draft with uncertainty visible, without inventing facts to fill a layout.
+
+Read [reference/geometry.md](reference/geometry.md) when creating or changing
+text, containers or connectors. Derive related coordinates from shared anchors;
+do not guess each field independently. Use ordinary code/arithmetic if helpful,
+but persist only the native scene, not a second diagram model or generator state.
+
+Who generates validates and repairs: run the Bundle's `scripts/validate.mjs`
+against the Design Files directory after writing scene files and the index.
+The script checks representation, references and ownership, not diagram meaning
+or aesthetics. Also perform the geometry and reading-order checks in the two
+references. With available browser/preview tools, inspect the rendered board at
+overview and readable zoom, repair problems, and inspect again. A valid JSON
+result is not visual acceptance. Without preview access, explicitly report that
+visual review was unavailable; do not claim the drawing looks correct. Use the ordinary
+host save/publication lifecycle; do not introduce a whiteboard-specific path.
+
+Remove a topic only when requested. Remove its index entry and order member;
+do not delete unrelated scene/image files or garbage-collect shared attachments.
+Unreferenced old files can remain recoverable in history. Canvas pan, zoom,
+selection and editing-tool state are not durable design facts.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/reference/artifact-contract.md

@@ -0,0 +1,56 @@
+# Whiteboard file contract
+
+For canvas generation or revision, read [the canvas guide](canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+`whiteboard/whiteboard.json` contains only the index:
+
+```json
+{"boards":{"idea":{"id":"idea","title":"Initial idea","artifact_file":"whiteboard/boards/idea.json"}},"board_order":["idea"]}
+```
+
+IDs contain ASCII letters, digits, `_` or `-` (1–128 characters). Index keys
+equal IDs; the order contains every board exactly once. Empty indexes are valid.
+Each board's exact scene path is `whiteboard/boards/<id>.json`.
+
+Scenes contain `elements` (native Excalidraw elements, retaining their IDs and
+all native geometry/bindings), `appState: {viewBackgroundColor: "#ffffff"}` and
+`files` (image references). Never put scene elements or base64 in the index.
+An empty scene is `{"elements":[],"appState":{"viewBackgroundColor":"#ffffff"},"files":{}}`.
+Use rectangle, ellipse, diamond, line, arrow, text, freedraw, image or frame.
+Embedded websites/iframes are not supported. Retain native element fields on
+edits; do not convert the scene into a second domain graph. Selection/zoom/tool
+state stays in the Panel. A minimal editable rectangle is:
+
+```json
+{"id":"box-1","type":"rectangle","x":80,"y":80,"width":220,"height":100,"angle":0,"strokeColor":"#1e1e1e","backgroundColor":"transparent","fillStyle":"solid","strokeWidth":2,"strokeStyle":"solid","roughness":1,"opacity":100,"groupIds":[],"frameId":null,"roundness":null,"seed":1,"version":1,"versionNonce":1,"isDeleted":false,"boundElements":null,"updated":1,"link":null,"locked":false}
+```
+
+Text elements additionally carry text/originalText, fontSize, fontFamily (use 2
+for the built-in sans-serif family), textAlign, verticalAlign, containerId,
+autoResize and lineHeight. Lines/arrows carry points and their native bindings.
+Bindings must refer to elements in the same scene. For coordinate construction,
+text sizing and endpoint checks, use [geometry.md](geometry.md). Check native rendering when
+authoring unfamiliar element kinds; structural validation is not visual proof.
+
+Image elements refer to `fileId`. `files[fileId]` is
+`{id, path, mimeType, created}`; path is
+`whiteboard/attachments/<fileId>.png|jpg|webp` matching PNG/JPEG/WebP MIME.
+Bytes are separate artifacts, never data URLs in persisted scene/index. Keep
+references used by deleted elements too, so undo does not lose images.
+The Panel hydrates these refs into native editor files and dehydrates uploads
+on the existing atomic save. Missing images must not silently erase references.
+
+Validation (Node only, no project/host imports or npm dependencies):
+
+```sh
+node /absolute/bundle/scripts/validate.mjs /absolute/project/design_files
+```
+
+The index schema/declarative validator is also used by the common host. The
+scene format helper lives in this Bundle and remains its CLI authority. The
+declarative Panel uses the shared native Excalidraw component; compatibility
+tests check that its serialized scenes satisfy this Bundle helper. Core owns
+only UI bindings, not another whiteboard domain model. No preview SVG or screenshot is
+required to edit, save or reopen a board.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/reference/canvas-guide.md

@@ -0,0 +1,39 @@
+# Native editable whiteboard
+
+Shared design/reconstruction reading entry. [The file contract](artifact-contract.md)
+owns index, scene, image-reference and validation format.
+[The drawing method](drawing-method.md) owns composition/reading order, and
+[native geometry](geometry.md) owns text sizing, coordinates, endpoints and reciprocal bindings.
+Preserve these specialist resources in place; this entry does not replace them.
+
+## Facts and drawing semantics
+
+`whiteboard/whiteboard.json` is the index; each exact `whiteboard/boards/<id>.json`
+is its editable Excalidraw scene authority. One topic is one board. Distinguish
+user statements, proposals and uncertainty. Shapes/notes/connectors explain ideas,
+not automatically canonical business relations or approved policy. Reconstruction
+preserves original meaning, native IDs/geometry and relevant supplied styling.
+
+## Composition, ports, routing and unknowns
+
+Choose a reading arrangement for the relationships, not a compulsory flowchart.
+Retain unaffected positions and native geometry. Follow `geometry.md` for actual
+text/container bounds and arrow points/bindings; they are native scene data,
+not the view-only coordinates of a domain graph. Native attach-point spacing
+may differ from the AI constellation's one-midpoint rule. Keep corridors and
+labels clear without shrinking all text or removing requested ideas. Unfamiliar
+element formats need real rendering review; structural validity alone does not
+establish correct geometry. Missing image bytes never erase their references.
+
+## Interaction, saving and examples
+
+The shared `canvas_workspace`/native editor reads and edits that same scene.
+Keep image bytes in attachments, never base64 in index/scene; retained deleted
+element references protect undo. Index and changed scene/images use the existing
+atomic save/publication path. Pan/zoom/selection/tool are local view state.
+Preserve native editable elements, not a flattened screenshot or second graph.
+Use the existing file/geometry examples. Run the Bundle scene validator and
+check real endpoints, reciprocal bindings, long CJK labels, reading order,
+missing images, resize and a local edit/undo where supported. Report structure,
+visual review and durable save/reopen separately. Without a preview, disclose
+that visual review is unverified; do not install a new runtime to claim success.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/reference/drawing-method.md

@@ -0,0 +1,78 @@
+# Compose a readable, editable whiteboard
+
+## Start with the explanation
+
+Identify the question the drawing should answer and the intended reader. Extract
+the main relationships, then choose a dominant reading order. Distinguish what
+the user supplied from hypotheses. Neither a missing branch nor an empty row
+authorizes inventing a business rule, emotion, metric or product feature.
+
+Choose a starting arrangement; these are options, not a required taxonomy:
+
+| Meaning | Useful arrangement | What carries the meaning |
+| --- | --- | --- |
+| Stages of an experience | Columns by stage, aligned rows for actions/support/problems | Alignment connects supporting notes to the stage; arrows only for actual transitions |
+| A decision or causal process | Main path with branches in reserved side space | Label the branch condition and direction |
+| Components and their interactions | Clusters by responsibility or boundary | Connect named endpoints; label what crosses a boundary |
+| Categories or exploration | Spatial clusters, headings and loose notes | Proximity and containment; no obligatory arrows |
+| Alternatives and tradeoffs | Shared comparison rows or columns | Comparable criteria, explicit unknowns |
+| Recurring feedback | Main path plus a separate return corridor | The return destination and the reason for returning |
+
+Do not force an open brainstorming canvas into a flowchart. Do not add a
+sentiment curve merely because a drawing is called a user journey. Use such a
+curve only when the input actually supports it. Follow a user's chosen visual
+style even when it differs from these defaults.
+
+## Allocate space before drawing details
+
+Reserve regions for the main story, supporting annotations and returns. Estimate
+text sizes before choosing node dimensions. Pick a readable base font and a
+consistent spacing unit, then reuse them across related elements. In a new board,
+roughly 18–24 scene units for primary labels is a useful starting point, not a
+guarantee of readability at the eventual zoom.
+
+Use a small, meaningful vocabulary of shapes. A diamond should indicate a
+decision, not simply make a problem note look different. Show priority through
+placement, size and restrained emphasis. Color can distinguish roles, but text
+and position must communicate the same distinction without color.
+
+Keep explanations near the thing they explain. A stage-aligned support note does
+not need another arrow just to repeat that association. Keep a legend outside the
+main routes, and omit it when direct labels already explain the visual language.
+
+When the board becomes hard to scan, first shorten labels and remove redundant
+connections. Then use an overview with detail regions on the same topic board.
+Do not silently discard requested content or create extra topics merely to meet
+a fixed node budget. Element count includes text and connectors: it is not the
+same as the number of ideas.
+
+## Example: experience with supporting systems
+
+For a research journey with phases, assistance and return paths:
+
+- Place the phases in reading order across the main row.
+- Align assistance notes beneath their phases; reserve a separate band for
+  shared tools if needed. Use headings rather than a connector from every note.
+- Route genuine feedback outside the occupied rows, with the destination and
+  trigger visible. If several returns dominate the overview, put their detail
+  in a nearby region rather than drawing long crossing diagonals through it.
+
+This is a composition example, not a required set of research phases or features.
+The same approach works for onboarding, purchasing or incident handling.
+
+## Review as a reader, then as an editor
+
+At overview zoom: can the reader find the starting point, main story and emphasis?
+At readable zoom: can they trace each important relationship without guessing?
+Check clipped labels, unrelated line crossings and dense annotation blocks.
+Review meaning as well as shape: a visually neat arrow in the wrong direction is
+still wrong. Do not solve crowding by shrinking every label.
+
+For edits, preserve unaffected element IDs, positions and user styling. Group
+objects that should move together (for example a local annotation), not all
+stages just because they share a category. Native text/arrow bindings provide
+relationships; visual proximity alone does not create an editable binding.
+
+The final handoff should name the topic, explain any material assumptions and
+state whether the rendered result was inspected. Do not substitute a screenshot
+or flattened image for the user's editable scene.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/reference/geometry.md

@@ -0,0 +1,79 @@
+# Native scene geometry
+
+The scene is the editable authority. A structurally valid element can still have
+incorrect geometry. Resolve geometry before serialization and check it after
+changes; the Bundle validator does not measure fonts or route connectors.
+
+## Text and containers
+
+Use the actual text, font size and line height to plan the box, not a guessed
+height copied from another label. With explicit line breaks, a useful minimum is
+`lineCount * fontSize * lineHeight`; wrapping may require more. Add interior
+padding to container dimensions. Exact width depends on font metrics, including
+CJK and fallback fonts; character counts alone are not a reliable measurement.
+Inspect rendering when possible. Without measurement, leave conservative room
+and mark visual review as unverified.
+
+Keep `text` and `originalText` consistent when changing content. For container
+text, set `containerId` and the container's matching `boundElements` text entry.
+Respect native alignment, wrapping and auto-resize behavior; do not assume
+`autoResize` will repair arbitrary stale dimensions during every load.
+Diamonds and ellipses have less usable label space than their bounding rectangle.
+
+Example: 10 explicit lines at font size 20 and line height 1.25 need about 250
+units of text height before padding. A 160-high card cannot accommodate that by
+declaring the text height to be 140. Shorten, wrap/reflow with adequate space, or
+separate the explanation; do not falsify its dimensions.
+
+## Connectors: intent and coordinates must agree
+
+For an unrotated native line/arrow, points are relative to the element origin:
+`absolutePoint = [element.x + point[0], element.y + point[1]]`.
+Derive points by subtracting the chosen origin from intended absolute anchors.
+Do not confuse an end coordinate with a displacement. For rotated or elbowed
+native elements, retain their format-specific geometry; inspect the native
+implementation/rendering before authoring unfamiliar fields.
+
+For a new unrotated polyline, dimensions follow the point extents:
+`width = max(point.x) - min(point.x)` and similarly for height. Negative relative
+coordinates are valid; they do not mean the corresponding dimension is negative.
+
+A worked construction (no special tool required):
+
+```js
+// Source right-edge anchor and destination left-edge anchor.
+const source = { x: 80, y: 160, width: 200, height: 100 }
+const target = { x: 440, y: 360, width: 200, height: 100 }
+const start = [source.x + source.width + 8, source.y + source.height / 2]
+const end = [target.x - 8, target.y + target.height / 2]
+const corridorX = (start[0] + end[0]) / 2
+const absolute = [start, [corridorX, start[1]], [corridorX, end[1]], end]
+const points = absolute.map(([x, y]) => [x - start[0], y - start[1]])
+// x/y = start; points = [[0,0],[72,0],[72,200],[144,200]].
+// width = 144; height = 200. Supply the remaining native arrow fields.
+```
+
+Choose a corridor that is actually empty, not always the midpoint. Straight lines
+are useful for aligned neighbors; bent routes often clarify returns and dense
+relationships. Diagonals are allowed when they improve the sketch. Avoid running
+through unrelated shapes or text. Separate shared-edge attach points so arrows
+remain distinguishable. Keep connector labels off the stroke and nearby nodes.
+
+Bindings encode which objects connect; they are not a substitute for coordinates.
+The first/last absolute points must be near the intended source/target boundaries
+with the chosen gap. Set `startBinding`/`endBinding` and reciprocal arrow entries
+on the target shapes consistently. Arrowheads must indicate the intended direction.
+On moving or resizing a bound shape, also re-evaluate affected connector geometry;
+do not assume a file load automatically reroutes it.
+
+## Pre-publication checks
+
+- Calculate absolute endpoints of changed arrows. Compare to their bound shapes,
+  not just to whether those IDs exist. Check all bends as well as endpoints.
+- Compare explicit text line height to available space; inspect wrapping, fallback
+  fonts and shaped containers in a preview where available.
+- Check route corridors, labels and any intentional overlap at readable zoom.
+- Run the existing structural validator, then visually inspect and repair with
+  available preview tools. Neither check replaces the other. If preview is not
+  available, report that limitation rather than installing a new runtime or
+  claiming aesthetic validation.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/schema.yaml

@@ -0,0 +1,18 @@
+type: object
+additional_properties: false
+required: [boards, board_order]
+properties:
+  boards:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [id, title, artifact_file]
+      properties:
+        id: { type: string }
+        title: { type: string }
+        artifact_file: { type: string }
+  board_order:
+    knowledge: { role: metadata }
+    type: array
+    items: { type: string }

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/whiteboard/validation.yaml

@@ -0,0 +1,18 @@
+skill: whiteboard
+rules:
+  - id: scene_files
+    scope: [state, completion]
+    code: whiteboard.missing_scene
+    check:
+      referenced_files: ["boards.*.artifact_file"]
+  - id: board_order
+    scope: [state, completion]
+    code: whiteboard.invalid_order
+    check:
+      order_refs_map: { order: board_order, map: boards }
+  - id: titles
+    scope: [state]
+    code: whiteboard.empty_title
+    check:
+      for_each_in_order: { order: board_order, map: boards }
+      non_empty_string: title