Arcturus-Morningstar-Extended/docs/superpowers/specs/2026-06-13-furnidata-create-if-missing-design.md

Furni Editor — create furnidata entry if missing (upsert)

Date: 2026-06-13 Status: Approved design → implementation Repos: Arcturus-Morningstar-Extended (emulator, primary), Nitro-V3 (client, minor)

Problem

In the in-client Furni Editor, many furni have no matching entry in the furnidata (split-tier *.json5 files). Today the editor detects this (furniDataEntry === null), shows a "Public Name (DB fallback)" and locks the name/description fields with the warning "this furni has no matching furnidata entry … so its display name can't be edited here." FurnidataWriter.write() is edit-only — it refuses classnames absent from furnidata. There is no path to create the missing entry.

Goal: let an operator create the missing furnidata entry directly from the editor, so the furni gets a real, editable name/description.

Decisions (from brainstorming)

1. Trigger = upsert Save. When the entry is missing, the name/desc fields are unlocked (name prefilled from the DB Public Name); the existing "Save name/desc" creates the entry if absent, edits it if present. No separate button beyond a relabel ("Create entry" when missing).
2. Completeness = full entry seeded from items_base. The created entry is a complete furnidata object (structural fields read from the item's DB row), not a name-only stub.
3. Target = config key furnidata.editor.create_tier (default custom). Split-tier → that tier file; single-file furnidata → the single file.

Approach

Reuse the existing FurniEditorUpdateFurnidata packet (outgoing header 10046, result 10044) and make the server handler upsert. Rejected alternative: a dedicated Create packet (10050) — unnecessary, because the create needs no extra client-supplied fields (the server reads items_base for the structural fields and takes name/desc from the existing 10046 payload).

Net wire impact: none. No renderer changes, no new packet. Only:

• Emulator: a new FurnidataWriter.create(...) + the 10046 handler becomes upsert + one config key + an items_base → furnidata field mapper.
• Client: unlock the name/desc fields when the entry is missing + relabel Save.

Emulator changes (Java)

1. habbohotel/items/FurnidataWriter.create(...)

New method, mirrors write()'s safety (locate target file, backup + atomic write, preserve JSON5 formatting/comments):

• Resolve target file: read config furnidata.editor.create_tier (default custom). If split-tier (manifest present) → that tier's file (create the file with a valid empty-array JSON5 shell if it doesn't exist yet). If single-file furnidata → the single file.
• Append a complete entry object (see field mapping) to the correct array (roomitemtypes for floor / wallitemtypes for wall).
• Guards: refuse if the classname already exists anywhere in furnidata (caller routes to edit instead); refuse if the chosen id (sprite id) is already used by a different classname (id collision would break roomItem.name.{id} / getFloorItemData(typeId) resolution).
• Return a result enum/boolean (created / already-exists / id-collision / io-error) so the handler can message the operator precisely.

2. FurniEditorUpdateFurnidataEvent (header 10046) → upsert

• Resolve classname + the full items_base row from itemId (handler already resolves classname).
• If furnidata has the classname → existing edit path (write()).
• Else → build the complete entry from items_base + submitted name/desc → FurnidataWriter.create(...).
• After either path (unchanged from edit): FurnitureTextProvider.reindexFromSource(), broadcast FurnitureDataReloadComposer (10047), mirror name into items_base.public_name, audit log (action "create" vs "edit"), respond FurniEditorResultComposer (10044) with success/precise error.
• Permission ACC_CATALOGFURNI + 1000ms rate-limit (unchanged).

3. Config key

furnidata.editor.create_tier (default custom), read where the writer resolves the target file.

4. items_base → furnidata field mapping (helper)

Read the item's DB definition and map to furnidata JSON. Minimum complete set (exact column/field names verified during implementation against the FurnidataReader schema + items_base):

• id = item sprite id (the visual/type id — MUST match so the furni resolves its name/data), classname = item_name,
• type = "s" (floor) / "i" (wall) from the item type,
• name = submitted name (fallback: public_name → classname), description = submitted description,
• xdim/ydim = width/length, canstandon/cansiton/canlayon from the item's stand/sit/lay flags, plus the standard furnidata defaults for the remaining fields (partcolors, offerid = -1, buyout, bc, excludeddynamic, customparams, specialtype, furniline, environment, rare, revision, category).

Client changes (React) — FurniEditorEditView.tsx

• When furniDataEntry === null: unlock the name/description inputs (currently gated by the furnidataEditable memo), prefill name from item.publicName, description blank. Replace the "can't be edited here" warning with an informational note: "No furnidata entry yet — saving will create one in the «custom» tier." Relabel the Save button to "Create entry" while missing.
• The Save handler is unchanged — it already sends FurniEditorUpdateFurnidataComposer(itemId, { name, description }).
• On FurniEditorResultEvent success, re-fetch detail (FurniEditorDetailComposer(itemId)) so furniDataEntry populates and the UI flips to normal edit mode.

Data flow

Save (entry missing)
  → 10046 UpdateFurnidata(itemId, {name, desc})
  → handler: classname absent → build complete entry from items_base + name/desc
  → FurnidataWriter.create(...) into the custom tier (atomic + backup)
  → reindexFromSource() + broadcast 10047 FurnitureDataReload
       → every client's catalog/inventory/infostand refreshes; the rendered
         furni now resolves its real name
  → mirror items_base.public_name
  → audit "create"
  → 10044 result(success)
  → client re-fetches detail → entry now present → normal edit mode

Error handling / edge cases

• Classname already present (lookup race) → routed to edit (upsert).
• Sprite id already used by a different classname → refuse + "id N already used by classname X".
• items_base row missing → refuse + error (shouldn't happen for a known item).
• Tier file absent → created with a valid JSON5 shell.
• Empty submitted name → fall back to public_name, else classname.
• Concurrency: reuse write()'s file lock + atomic write + backup.

Testing

• Emulator unit: FurnidataWriter.create writes a valid JSON5 entry into the target tier; idempotency guard (already-exists); id-collision guard; round-trips through FurnidataReader.
• Runtime (Chrome handle available): in the Furni Editor select a furni with no furnidata entry (the live "DB fallback" case), type a name, Save → entry created, furni name updates live (10047 broadcast), reopen → entry present and editable. Verify the new object lands in the custom tier file and FurnidataReader parses it.

Out of scope

• No new wire packet; no renderer changes.
• No bulk/batch creation; one furni at a time via the editor.
• No editing of structural fields from the UI (only name/desc, as today); the structural fields are seeded once at creation from items_base.
• No deletion of furnidata entries (separate concern).